## GstBuffer GstBuffer — Data-passing buffer type |

## Synopsis

    #include <gst/gst.h>

    struct              GstBuffer;
    enum                GstBufferFlags;
    #define             GST_BUFFER_FLAGS                    (buf)
    #define             GST_BUFFER_FLAG_IS_SET              (buf,
                                                             flag)
    #define             GST_BUFFER_FLAG_SET                 (buf,
                                                             flag)
    #define             GST_BUFFER_FLAG_UNSET               (buf,
                                                             flag)
    #define             GST_BUFFER_PTS                      (buf)
    #define             GST_BUFFER_DTS                      (buf)
    #define             GST_BUFFER_DURATION                 (buf)
    #define             GST_BUFFER_OFFSET                   (buf)
    #define             GST_BUFFER_OFFSET_END               (buf)
    #define             GST_BUFFER_OFFSET_NONE
    #define             GST_BUFFER_DURATION_IS_VALID        (buffer)
    #define             GST_BUFFER_PTS_IS_VALID             (buffer)
    #define             GST_BUFFER_DTS_IS_VALID             (buffer)
    #define             GST_BUFFER_OFFSET_IS_VALID          (buffer)
    #define             GST_BUFFER_OFFSET_END_IS_VALID      (buffer)
    #define             GST_BUFFER_IS_DISCONT               (buffer)
    GstBuffer *         gst_buffer_new                      (void);
    GstBuffer *         gst_buffer_new_allocate             (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);
    GstBuffer *         gst_buffer_new_wrapped              (gpointer data,
                                                             gsize size);
    GstBuffer *         gst_buffer_new_wrapped_full         (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GstBuffer *         gst_buffer_ref                      (GstBuffer *buf);
    void                gst_buffer_unref                    (GstBuffer *buf);
    gsize               gst_buffer_get_sizes                (GstBuffer *buffer,
                                                             gsize *offset,
                                                             gsize *maxsize);
    gsize               gst_buffer_get_size                 (GstBuffer *buffer);
    gsize               gst_buffer_get_sizes_range          (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             gsize *offset,
                                                             gsize *maxsize);
    gboolean            gst_buffer_resize_range             (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             gssize offset,
                                                             gssize size);
    void                gst_buffer_resize                   (GstBuffer *buffer,
                                                             gssize offset,
                                                             gssize size);
    void                gst_buffer_set_size                 (GstBuffer *buffer,
                                                             gssize size);
    GstMemory *         gst_buffer_peek_memory              (GstBuffer *buffer,
                                                             guint idx);
    guint               gst_buffer_n_memory                 (GstBuffer *buffer);
    void                gst_buffer_insert_memory            (GstBuffer *buffer,
                                                             gint idx,
                                                             GstMemory *mem);
    void                gst_buffer_replace_memory_range     (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             GstMemory *mem);
    GstMemory *         gst_buffer_get_memory_range         (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length);
    void                gst_buffer_remove_memory_range      (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length);
    gboolean            gst_buffer_find_memory              (GstBuffer *buffer,
                                                             gsize offset,
                                                             gsize size,
                                                             guint *idx,
                                                             guint *length,
                                                             gsize *skip);
    void                gst_buffer_prepend_memory           (GstBuffer *buffer,
                                                             GstMemory *mem);
    void                gst_buffer_append_memory            (GstBuffer *buffer,
                                                             GstMemory *mem);
    void                gst_buffer_replace_memory           (GstBuffer *buffer,
                                                             guint idx,
                                                             GstMemory *mem);
    void                gst_buffer_replace_all_memory       (GstBuffer *buffer,
                                                             GstMemory *mem);
    GstMemory *         gst_buffer_get_memory               (GstBuffer *buffer,
                                                             guint idx);
    GstMemory *         gst_buffer_get_all_memory           (GstBuffer *buffer);
    void                gst_buffer_remove_memory            (GstBuffer *buffer,
                                                             guint idx);
    void                gst_buffer_remove_all_memory        (GstBuffer *buffer);
    gboolean            gst_buffer_map                      (GstBuffer *buffer,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    gboolean            gst_buffer_map_range                (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);
    void                gst_buffer_unmap                    (GstBuffer *buffer,
                                                             GstMapInfo *info);
    gint                gst_buffer_memcmp                   (GstBuffer *buffer,
                                                             gsize offset,
                                                             gconstpointer mem,
                                                             gsize size);
    gsize               gst_buffer_extract                  (GstBuffer *buffer,
                                                             gsize offset,
                                                             gpointer dest,
                                                             gsize size);
    void                gst_buffer_extract_dup              (GstBuffer *buffer,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer *dest,
                                                             gsize *dest_size);
    gsize               gst_buffer_fill                     (GstBuffer *buffer,
                                                             gsize offset,
                                                             gconstpointer src,
                                                             gsize size);
    gsize               gst_buffer_memset                   (GstBuffer *buffer,
                                                             gsize offset,
                                                             guint8 val,
                                                             gsize size);
    enum                GstBufferCopyFlags;
    #define             GST_BUFFER_COPY_METADATA
    #define             GST_BUFFER_COPY_ALL
    GstBuffer *         gst_buffer_copy                     (const GstBuffer *buf);
    gboolean            gst_buffer_copy_into                (GstBuffer *dest,
                                                             GstBuffer *src,
                                                             GstBufferCopyFlags flags,
                                                             gsize offset,
                                                             gsize size);
    GstBuffer *         gst_buffer_copy_region              (GstBuffer *parent,
                                                             GstBufferCopyFlags flags,
                                                             gsize offset,
                                                             gsize size);
    #define             gst_buffer_is_writable              (buf)
    #define             gst_buffer_make_writable            (buf)
    gboolean            gst_buffer_replace                  (GstBuffer **obuf,
                                                             GstBuffer *nbuf);
    GstBuffer *         gst_buffer_append                   (GstBuffer *buf1,
                                                             GstBuffer *buf2);
    GstBuffer *         gst_buffer_append_region            (GstBuffer *buf1,
                                                             GstBuffer *buf2,
                                                             gssize offset,
                                                             gssize size);
    GstMeta *           gst_buffer_get_meta                 (GstBuffer *buffer,
                                                             GType api);
    GstMeta *           gst_buffer_add_meta                 (GstBuffer *buffer,
                                                             const GstMetaInfo *info,
                                                             gpointer params);
    gboolean            gst_buffer_remove_meta              (GstBuffer *buffer,
                                                             GstMeta *meta);
    GstMeta *           gst_buffer_iterate_meta             (GstBuffer *buffer,
                                                             gpointer *state);
    gboolean            (*GstBufferForeachMetaFunc)         (GstBuffer *buffer,
                                                             GstMeta **meta,
                                                             gpointer user_data);
    gboolean            gst_buffer_foreach_meta             (GstBuffer *buffer,
                                                             GstBufferForeachMetaFunc func,
                                                             gpointer user_data);

## Description

Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the GstMemory blocks that the buffer contains.

Buffers are usually created with `gst_buffer_new()`. After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

Example 3. Creating a buffer for a video frame

    1
    2
    3
    4
    5
    6
    7
    8
    9
    GstBuffer *buffer;
    GstMemory *memory;
    gint size, width, height, bpp;
    ...
    size = width * height * bpp;
    buffer = gst_buffer_new ();
    memory = gst_allocator_alloc (NULL, size, NULL);
    gst_buffer_insert_memory (buffer, -1, memory);
    ...

Alternatively, use `gst_buffer_new_allocate()` to create a buffer with preallocated data of a given size.

Buffers can contain a list of GstMemory objects. You can retrieve how many memory objects with `gst_buffer_n_memory()` and you can get a pointer to memory with `gst_buffer_peek_memory()`

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to GST_CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are GstClockTime values).

The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.

A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceeding CAPS event). Either or both can be set to GST_BUFFER_OFFSET_NONE.

`gst_buffer_ref()` is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer.

To efficiently create a smaller buffer out of an existing one, you can use `gst_buffer_copy_region()`. This method tries to share the memory objects between the two buffers.

If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using `gst_buffer_make_writable()`. This function is optimized so that a copy will only be made when it is necessary.

Several flags of the buffer can be set and unset with the `GST_BUFFER_FLAG_SET()` and `GST_BUFFER_FLAG_UNSET()` macros. Use `GST_BUFFER_FLAG_IS_SET()` to test if a certain GstBufferFlag is set.

Buffers can be efficiently merged into a larger buffer with `gst_buffer_append()`. Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with `gst_buffer_add_meta()`. Metadata can be retrieved with `gst_buffer_get_meta()`. See also GstMeta

An element should either unref the buffer or push it out on a src pad using `gst_pad_push()` (see GstPad).

Buffers are usually freed by unreffing them with `gst_buffer_unref()`. When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a GstBufferPool will be returned to the pool when the refcount drops to 0.

Last reviewed on 2012-03-28 (0.11.3)

## Details

### struct GstBuffer

    struct GstBuffer {
      GstMiniObject          mini_object;

      GstBufferPool         *pool;

      /* timestamp */
      GstClockTime           pts;
      GstClockTime           dts;
      GstClockTime           duration;

      /* media specific offset */
      guint64                offset;
      guint64                offset_end;
    };

The structure of a GstBuffer. Use the associated macros to access the public variables.

GstMiniObject `mini_object`; | the parent structure
GstBufferPool *`pool`; | pointer to the pool owner of the buffer
GstClockTime `pts`; | presentation timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the pts is not known or relevant. The pts contains the timestamp when the media should be presented to the user.
GstClockTime `dts`; | decoding timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the dts is not known or relevant. The dts contains the timestamp when the media should be processed.
GstClockTime `duration`; | duration in time of the buffer data, can be GST_CLOCK_TIME_NONE when the duration is not known or relevant.
guint64 `offset`; | a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
guint64 `offset_end`; | the last offset contained in this buffer. It has the same format as `offset`.

### enum GstBufferFlags

    typedef enum {
      GST_BUFFER_FLAG_LIVE        = (GST_MINI_OBJECT_FLAG_LAST << 0),
      GST_BUFFER_FLAG_DECODE_ONLY = (GST_MINI_OBJECT_FLAG_LAST << 1),
      GST_BUFFER_FLAG_DISCONT     = (GST_MINI_OBJECT_FLAG_LAST << 2),
      GST_BUFFER_FLAG_RESYNC      = (GST_MINI_OBJECT_FLAG_LAST << 3),
      GST_BUFFER_FLAG_CORRUPTED   = (GST_MINI_OBJECT_FLAG_LAST << 4),
      GST_BUFFER_FLAG_MARKER      = (GST_MINI_OBJECT_FLAG_LAST << 5),
      GST_BUFFER_FLAG_HEADER      = (GST_MINI_OBJECT_FLAG_LAST << 6),
      GST_BUFFER_FLAG_GAP         = (GST_MINI_OBJECT_FLAG_LAST << 7),
      GST_BUFFER_FLAG_DROPPABLE   = (GST_MINI_OBJECT_FLAG_LAST << 8),
      GST_BUFFER_FLAG_DELTA_UNIT  = (GST_MINI_OBJECT_FLAG_LAST << 9),

      GST_BUFFER_FLAG_LAST        = (GST_MINI_OBJECT_FLAG_LAST << 16)
    } GstBufferFlags;

A set of buffer flags used to describe properties of a GstBuffer.

`GST_BUFFER_FLAG_LIVE` | the buffer is live data and should be discarded in the PAUSED state.
`GST_BUFFER_FLAG_DECODE_ONLY` | the buffer contains data that should be dropped because it will be clipped against the segment boundaries or because it does not contain data that should be shown to the user.
`GST_BUFFER_FLAG_DISCONT` | the buffer marks a data discontinuity in the stream. This typically occurs after a seek or a dropped buffer from a live or network source.
`GST_BUFFER_FLAG_RESYNC` | the buffer timestamps might have a discontinuity and this buffer is a good point to resynchronize.
`GST_BUFFER_FLAG_CORRUPTED` | the buffer data is corrupted.
`GST_BUFFER_FLAG_MARKER` | the buffer contains a media specific marker. for video this is typically the end of a frame boundary, for audio this is usually the start of a talkspurt.
`GST_BUFFER_FLAG_HEADER` | the buffer contains header information that is needed to decode the following data.
`GST_BUFFER_FLAG_GAP` | the buffer has been created to fill a gap in the stream and contains media neutral data (elements can switch to optimized code path that ignores the buffer content).
`GST_BUFFER_FLAG_DROPPABLE` | the buffer can be dropped without breaking the stream, for example to reduce bandwidth.
`GST_BUFFER_FLAG_DELTA_UNIT` | this unit cannot be decoded independently.
`GST_BUFFER_FLAG_LAST` | additional media specific flags can be added starting from this flag.

### GST_BUFFER_FLAGS()

    #define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

A flags word containing GstBufferFlag flags set on this buffer.

`buf` : | a GstBuffer.

### GST_BUFFER_FLAG_IS_SET()

    #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)

Gives the status of a specific flag on a buffer.

`buf` : | a GstBuffer.
`flag` : | the GstBufferFlag to check.

### GST_BUFFER_FLAG_SET()

    #define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)

Sets a buffer flag on a buffer.

`buf` : | a GstBuffer.
`flag` : | the GstBufferFlag to set.

### GST_BUFFER_FLAG_UNSET()

    #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)

Clears a buffer flag.

`buf` : | a GstBuffer.
`flag` : | the GstBufferFlag to clear.

### GST_BUFFER_PTS()

    #define GST_BUFFER_PTS(buf)                     (GST_BUFFER_CAST(buf)->pts)

The presentation timestamp (pts) in nanoseconds (as a GstClockTime) of the data in the buffer. This is the timestamp when the media should be presented to the user. Value will be `GST_CLOCK_TIME_NONE` if the pts is unknown.

`buf` : | a GstBuffer.:

### GST_BUFFER_DTS()

    #define GST_BUFFER_DTS(buf)                     (GST_BUFFER_CAST(buf)->dts)

The decoding timestamp (dts) in nanoseconds (as a GstClockTime) of the data in the buffer. This is the timestamp when the media should be decoded or processed otherwise. Value will be `GST_CLOCK_TIME_NONE` if the dts is unknown.

`buf` : | a GstBuffer.:

### GST_BUFFER_DURATION()

    #define GST_BUFFER_DURATION(buf)                (GST_BUFFER_CAST(buf)->duration)

The duration in nanoseconds (as a GstClockTime) of the data in the buffer. Value will be `GST_CLOCK_TIME_NONE` if the duration is unknown.

`buf` : | a GstBuffer.

### GST_BUFFER_OFFSET()

    #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER_CAST(buf)->offset)

The offset in the source file of the beginning of this buffer.

`buf` : | a GstBuffer.

### GST_BUFFER_OFFSET_END()

    #define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER_CAST(buf)->offset_end)

The offset in the source file of the end of this buffer.

`buf` : | a GstBuffer.

### GST_BUFFER_OFFSET_NONE

    #define GST_BUFFER_OFFSET_NONE  ((guint64)-1)

Constant for no-offset return results.

### GST_BUFFER_DURATION_IS_VALID()

    #define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))

Tests if the duration is known.

`buffer` : | a GstBuffer

### GST_BUFFER_PTS_IS_VALID()

    #define GST_BUFFER_PTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_PTS (buffer)))

Tests if the pts is known.

`buffer` : | a GstBuffer

### GST_BUFFER_DTS_IS_VALID()

    #define GST_BUFFER_DTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DTS (buffer)))

Tests if the dts is known.

`buffer` : | a GstBuffer

### GST_BUFFER_OFFSET_IS_VALID()

    #define GST_BUFFER_OFFSET_IS_VALID(buffer)      (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the start offset is known.

`buffer` : | a GstBuffer

### GST_BUFFER_OFFSET_END_IS_VALID()

    #define GST_BUFFER_OFFSET_END_IS_VALID(buffer)  (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the end offset is known.

`buffer` : | a GstBuffer

### GST_BUFFER_IS_DISCONT()

    #define GST_BUFFER_IS_DISCONT(buffer)   (GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_DISCONT))

Tests if the buffer marks a discontinuity in the stream.

`buffer` : | a GstBuffer

### gst_buffer_new ()

    GstBuffer *         gst_buffer_new                      (void);

Creates a newly allocated buffer without any data.

MT safe.

Returns : | the new GstBuffer. [transfer full]

### gst_buffer_new_allocate ()

    GstBuffer *         gst_buffer_new_allocate             (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);

Tries to create a newly allocated buffer with data of the given size and extra parameters from `allocator`. If the requested amount of memory can't be allocated, NULL will be returned. The allocated buffer memory is not cleared.

When `allocator` is NULL, the default memory allocator will be used.

Note that when `size` == 0, the buffer will not have memory associated with it.

MT safe.

`allocator` : | the GstAllocator to use, or NULL to use the default allocator. [transfer none][allow-none]
`size` : | the size in bytes of the new buffer's data.
`params` : | optional parameters. [transfer none][allow-none]
Returns : | a new GstBuffer, or NULL if the memory couldn't be allocated. [transfer full]

### gst_buffer_new_wrapped ()

    GstBuffer *         gst_buffer_new_wrapped              (gpointer data,
                                                             gsize size);

Creates a new buffer that wraps the given `data`. The memory will be freed with g_free and will be marked writable.

MT safe.

`data` : | data to wrap. [array length=size][element-type guint8][transfer full]
`size` : | allocated size of `data`
Returns : | a new GstBuffer. [transfer full]

### gst_buffer_new_wrapped_full ()

    GstBuffer *         gst_buffer_new_wrapped_full         (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Allocate a new buffer that wraps the given memory. `data` must point to `maxsize` of memory, the wrapped buffer will have the region from `offset` and `size` visible.

When the buffer is destroyed, `notify` will be called with `user_data`.

The prefix/padding must be filled with 0 if `flags` contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

`flags` : | GstMemoryFlags
`data` : | data to wrap. [array length=size][element-type guint8][transfer none]
`maxsize` : | allocated size of `data`
`offset` : | offset in `data`
`size` : | size of valid data
`user_data` : | user_data. [allow-none]
`notify` : | called with `user_data` when the memory is freed. [allow-none][scope async][closure user_data]
Returns : | a new GstBuffer. [transfer full]

### gst_buffer_ref ()

    GstBuffer *         gst_buffer_ref                      (GstBuffer *buf);

Increases the refcount of the given buffer by one.

Note that the refcount affects the writeability of `buf` and its metadata, see `gst_buffer_is_writable()`. It is important to note that keeping additional references to GstBuffer instances can potentially increase the number of memcpy operations in a pipeline.

`buf` : | a GstBuffer.
Returns : | `buf`. [transfer full]

### gst_buffer_unref ()

    void                gst_buffer_unref                    (GstBuffer *buf);

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer with the associated metadata and memory will be freed.

`buf` : | a GstBuffer. [transfer full]

### gst_buffer_get_sizes ()

    gsize               gst_buffer_get_sizes                (GstBuffer *buffer,
                                                             gsize *offset,
                                                             gsize *maxsize);

Get the total size of the memory blocks in `b`.

When not `NULL`, `offset` will contain the offset of the data in the first memory block in `buffer` and `maxsize` will contain the sum of the size and `offset` and the amount of extra padding on the last memory block. `offset` and `maxsize` can be used to resize the buffer memory blocks with `gst_buffer_resize()`.

`buffer` : | a GstBuffer.
`offset` : | a pointer to the offset. [out]
`maxsize` : | a pointer to the maxsize. [out]
Returns : | total size of the memory blocks in `buffer`.

### gst_buffer_get_size ()

    gsize               gst_buffer_get_size                 (GstBuffer *buffer);

Get the total size of the memory blocks in `buffer`.

`buffer` : | a GstBuffer.
Returns : | total size of the memory blocks in `buffer`.

### gst_buffer_get_sizes_range ()

    gsize               gst_buffer_get_sizes_range          (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             gsize *offset,
                                                             gsize *maxsize);

Get the total size of `length` memory blocks stating from `idx` in `buffer`.

When not `NULL`, `offset` will contain the offset of the data in the memory block in `buffer` at `idx` and `maxsize` will contain the sum of the size and `offset` and the amount of extra padding on the memory block at `idx` + `length` -1. `offset` and `maxsize` can be used to resize the buffer memory blocks with `gst_buffer_resize_range()`.

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length
`offset` : | a pointer to the offset. [out]
`maxsize` : | a pointer to the maxsize. [out]
Returns : | total size of `length` memory blocks starting at `idx` in `buffer`.

### gst_buffer_resize_range ()

    gboolean            gst_buffer_resize_range             (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             gssize offset,
                                                             gssize size);

Set the total size of the `length` memory blocks starting at `idx` in `buffer`

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length
`offset` : | the offset adjustement
`size` : | the new size or -1 to just adjust the offset
Returns : | `TRUE` if resizing succeeded, `FALSE` otherwise.

### gst_buffer_resize ()

    void                gst_buffer_resize                   (GstBuffer *buffer,
                                                             gssize offset,
                                                             gssize size);

Set the offset and total size of the memory blocks in `buffer`.

`buffer` : | a GstBuffer.
`offset` : | the offset adjustement
`size` : | the new size or -1 to just adjust the offset

### gst_buffer_set_size ()

    void                gst_buffer_set_size                 (GstBuffer *buffer,
                                                             gssize size);

Set the total size of the memory blocks in `buffer`.

`buffer` : | a GstBuffer.
`size` : | the new size

### gst_buffer_peek_memory ()

    GstMemory *         gst_buffer_peek_memory              (GstBuffer *buffer,
                                                             guint idx);

Get the memory block at `idx` in `buffer`. The memory block stays valid until the memory block in `buffer` is removed, replaced or merged, typically with any call that modifies the memory in `buffer`.

Since this call does not influence the refcount of the memory, `gst_memory_is_writable()` can be used to check if `buffer` is the sole owner of the returned memory.

`buffer` : | a GstBuffer.
`idx` : | an index
Returns : | the GstMemory at `idx`. [transfer none]

### gst_buffer_n_memory ()

    guint               gst_buffer_n_memory                 (GstBuffer *buffer);

Get the amount of memory blocks that this buffer has. This amount is never larger than what `gst_buffer_get_max_memory()` returns.

`buffer` : | a GstBuffer.
Returns : | the amount of memory block in this buffer. [transfer full]

### gst_buffer_insert_memory ()

    void                gst_buffer_insert_memory            (GstBuffer *buffer,
                                                             gint idx,
                                                             GstMemory *mem);

Insert the memory block `mem` to `buffer` at `idx`. This function takes ownership of `mem` and thus doesn't increase its refcount.

Only `gst_buffer_get_max_memory()` can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.

`buffer` : | a GstBuffer.
`idx` : | the index to add the memory at, or -1 to append it to the end
`mem` : | a GstMemory. [transfer full]

### gst_buffer_replace_memory_range ()

    void                gst_buffer_replace_memory_range     (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             GstMemory *mem);

Replaces `length` memory blocks in `buffer` starting at `idx` with `mem`.

If `length` is -1, all memory starting from `idx` will be removed and replaced with `mem`.

`buffer` should be writable.

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length should not be 0
`mem` : | a GstMemory. [transfer full]

### gst_buffer_get_memory_range ()

    GstMemory *         gst_buffer_get_memory_range         (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length);

Get `length` memory blocks in `buffer` starting at `idx`. The memory blocks will be merged into one large GstMemory.

If `length` is -1, all memory starting from `idx` is merged.

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length
Returns : | a GstMemory that contains the merged data of `length` blocks starting at `idx`. Use `gst_memory_unref()` after usage. [transfer full]

### gst_buffer_remove_memory_range ()

    void                gst_buffer_remove_memory_range      (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length);

Remove `length` memory blocks in `buffer` starting from `idx`.

`length` can be -1, in which case all memory starting from `idx` is removed.

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length

### gst_buffer_find_memory ()

    gboolean            gst_buffer_find_memory              (GstBuffer *buffer,
                                                             gsize offset,
                                                             gsize size,
                                                             guint *idx,
                                                             guint *length,
                                                             gsize *skip);

Find the memory blocks that span `size` bytes starting from `offset` in `buffer`.

When this function returns `TRUE`, `idx` will contain the index of the first memory bock where the byte for `offset` can be found and `length` contains the number of memory blocks containing the `size` remaining bytes. `skip` contains the number of bytes to skip in the memory bock at `idx` to get to the byte for `offset`.

`size` can be -1 to get all the memory blocks after `idx`.

`buffer` : | a GstBuffer.
`offset` : | an offset
`size` : | a size
`idx` : | pointer to index. [out]
`length` : | pointer to length. [out]
`skip` : | pointer to skip. [out]
Returns : | `TRUE` when `size` bytes starting from `offset` could be found in `buffer` and `idx`, `length` and `skip` will be filled.

### gst_buffer_prepend_memory ()

    void                gst_buffer_prepend_memory           (GstBuffer *buffer,
                                                             GstMemory *mem);

Prepend the memory block `mem` to `buffer`. This function takes ownership of `mem` and thus doesn't increase its refcount.

This function is identical to `gst_buffer_insert_memory()` with an index of 0. See `gst_buffer_insert_memory()` for more details.

`buffer` : | a GstBuffer.
`mem` : | a GstMemory. [transfer full]

### gst_buffer_append_memory ()

    void                gst_buffer_append_memory            (GstBuffer *buffer,
                                                             GstMemory *mem);

Append the memory block `mem` to `buffer`. This function takes ownership of `mem` and thus doesn't increase its refcount.

This function is identical to `gst_buffer_insert_memory()` with an index of -1. See `gst_buffer_insert_memory()` for more details.

`buffer` : | a GstBuffer.
`mem` : | a GstMemory. [transfer full]

### gst_buffer_replace_memory ()

    void                gst_buffer_replace_memory           (GstBuffer *buffer,
                                                             guint idx,
                                                             GstMemory *mem);

Replaces the memory block at index `idx` in `buffer` with `mem`.

`buffer` : | a GstBuffer.
`idx` : | an index
`mem` : | a GstMemory. [transfer full]

### gst_buffer_replace_all_memory ()

    void                gst_buffer_replace_all_memory       (GstBuffer *buffer,
                                                             GstMemory *mem);

Replaces all memory in `buffer` with `mem`.

`buffer` : | a GstBuffer.
`mem` : | a GstMemory. [transfer full]

### gst_buffer_get_memory ()

    GstMemory *         gst_buffer_get_memory               (GstBuffer *buffer,
                                                             guint idx);

Get the memory block at index `idx` in `buffer`.

`buffer` : | a GstBuffer.
`idx` : | an index
Returns : | a GstMemory that contains the data of the memory block at `idx`. Use `gst_memory_unref()` after usage. [transfer full]

### gst_buffer_get_all_memory ()

    GstMemory *         gst_buffer_get_all_memory           (GstBuffer *buffer);

Get all the memory block in `buffer`. The memory blocks will be merged into one large GstMemory.

`buffer` : | a GstBuffer.
Returns : | a GstMemory that contains the merged memory. Use `gst_memory_unref()` after usage. [transfer full]

### gst_buffer_remove_memory ()

    void                gst_buffer_remove_memory            (GstBuffer *buffer,
                                                             guint idx);

Remove the memory block in `b` at index `i`.

`buffer` : | a GstBuffer.
`idx` : | an index

### gst_buffer_remove_all_memory ()

    void                gst_buffer_remove_all_memory        (GstBuffer *buffer);

Remove all the memory blocks in `buffer`.

`buffer` : | a GstBuffer.

### gst_buffer_map ()

    gboolean            gst_buffer_map                      (GstBuffer *buffer,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);

This function fills `info` with the GstMapInfo of all merged memory blocks in `buffer`.

`flags` describe the desired access of the memory. When `flags` is GST_MAP_WRITE, `buffer` should be writable (as returned from `gst_buffer_is_writable()`).

When `buffer` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in `info` should be unmapped with `gst_buffer_unmap()` after usage.

`buffer` : | a GstBuffer.
`info` : | info about the mapping. [out]
`flags` : | flags for the mapping
Returns : | `TRUE` if the map succeeded and `info` contains valid data.

### gst_buffer_map_range ()

    gboolean            gst_buffer_map_range                (GstBuffer *buffer,
                                                             guint idx,
                                                             gint length,
                                                             GstMapInfo *info,
                                                             GstMapFlags flags);

This function fills `info` with the GstMapInfo of `length` merged memory blocks starting at `idx` in `buffer`. When `length` is -1, all memory blocks starting from `idx` are merged and mapped.

`flags` describe the desired access of the memory. When `flags` is GST_MAP_WRITE, `buffer` should be writable (as returned from `gst_buffer_is_writable()`).

When `buffer` is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in `info` should be unmapped with `gst_buffer_unmap()` after usage.

`buffer` : | a GstBuffer.
`idx` : | an index
`length` : | a length
`info` : | info about the mapping. [out]
`flags` : | flags for the mapping
Returns : | `TRUE` if the map succeeded and `info` contains valid data.

### gst_buffer_unmap ()

    void                gst_buffer_unmap                    (GstBuffer *buffer,
                                                             GstMapInfo *info);

Release the memory previously mapped with `gst_buffer_map()`.

`buffer` : | a GstBuffer.
`info` : | a GstMapInfo

### gst_buffer_memcmp ()

    gint                gst_buffer_memcmp                   (GstBuffer *buffer,
                                                             gsize offset,
                                                             gconstpointer mem,
                                                             gsize size);

Compare `size` bytes starting from `offset` in `buffer` with the memory in `mem`.

`buffer` : | a GstBuffer.
`offset` : | the offset in `buffer`
`mem` : | the memory to compare. [array length=size][element-type guint8]
`size` : | the size to compare
Returns : | 0 if the memory is equal.

### gst_buffer_extract ()

    gsize               gst_buffer_extract                  (GstBuffer *buffer,
                                                             gsize offset,
                                                             gpointer dest,
                                                             gsize size);

Copy `size` bytes starting from `offset` in `buffer` to `dest`.

`buffer` : | a GstBuffer.
`offset` : | the offset to extract
`dest` : | the destination address
`size` : | the size to extract
Returns : | The amount of bytes extracted. This value can be lower than `size` when `buffer` did not contain enough data.

### gst_buffer_extract_dup ()

    void                gst_buffer_extract_dup              (GstBuffer *buffer,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer *dest,
                                                             gsize *dest_size);

Extracts a copy of at most `size` bytes the data at `offset` into a GBytes. `dest` must be freed using `g_free()` when done.

`buffer` : | a GstBuffer
`offset` : | the offset to extract
`size` : | the size to extract
`dest` : | A pointer where the destination array will be written. [array length=dest_size][element-type guint8][out]
`dest_size` : | A location where the size of `dest` can be written. [out]

Since 1.0.10

### gst_buffer_fill ()

    gsize               gst_buffer_fill                     (GstBuffer *buffer,
                                                             gsize offset,
                                                             gconstpointer src,
                                                             gsize size);

Copy `size` bytes from `src` to `buffer` at `offset`.

`buffer` : | a GstBuffer.
`offset` : | the offset to fill
`src` : | the source address. [array length=size][element-type guint8]
`size` : | the size to fill
Returns : | The amount of bytes copied. This value can be lower than `size` when `buffer` did not contain enough data.

### gst_buffer_memset ()

    gsize               gst_buffer_memset                   (GstBuffer *buffer,
                                                             gsize offset,
                                                             guint8 val,
                                                             gsize size);

Fill `buf` with `size` bytes with `val` starting from `offset`.

`buffer` : | a GstBuffer.
`offset` : | the offset in `buffer`
`val` : | the value to set
`size` : | the size to set
Returns : | The amount of bytes filled. This value can be lower than `size` when `buffer` did not contain enough data.

### enum GstBufferCopyFlags

    typedef enum {
      GST_BUFFER_COPY_NONE           = 0,
      GST_BUFFER_COPY_FLAGS          = (1 << 0),
      GST_BUFFER_COPY_TIMESTAMPS     = (1 << 1),
      GST_BUFFER_COPY_META           = (1 << 2),
      GST_BUFFER_COPY_MEMORY         = (1 << 3),
      GST_BUFFER_COPY_MERGE          = (1 << 4),
      GST_BUFFER_COPY_DEEP           = (1 << 5)
    } GstBufferCopyFlags;

A set of flags that can be provided to the `gst_buffer_copy_into()` function to specify which items should be copied.

`GST_BUFFER_COPY_NONE` | copy nothing
`GST_BUFFER_COPY_FLAGS` | flag indicating that buffer flags should be copied
`GST_BUFFER_COPY_TIMESTAMPS` | flag indicating that buffer pts, dts, duration, offset and offset_end should be copied
`GST_BUFFER_COPY_META` | flag indicating that buffer meta should be copied
`GST_BUFFER_COPY_MEMORY` | flag indicating that buffer memory should be reffed and appended to already existing memory. Unless the memory is marked as NO_SHARE, no actual copy of the memory is made but it is simply reffed. Add `GST_BUFFER_COPY_DEEP` to force a real copy.
`GST_BUFFER_COPY_MERGE` | flag indicating that buffer memory should be merged
`GST_BUFFER_COPY_DEEP` | flag indicating that memory should always be copied instead of reffed (Since 1.2)

### GST_BUFFER_COPY_METADATA

    #define             GST_BUFFER_COPY_METADATA

Combination of all possible metadata fields that can be copied with `gst_buffer_copy_into()`.

### GST_BUFFER_COPY_ALL

    #define GST_BUFFER_COPY_ALL  ((GstBufferCopyFlags)(GST_BUFFER_COPY_METADATA | GST_BUFFER_COPY_MEMORY))

Combination of all possible fields that can be copied with `gst_buffer_copy_into()`.

### gst_buffer_copy ()

    GstBuffer *         gst_buffer_copy                     (const GstBuffer *buf);

Create a copy of the given buffer. This will also make a newly allocated copy of the data the source buffer contains.

`buf` : | a GstBuffer.
Returns : | a new copy of `buf`. [transfer full]

### gst_buffer_copy_into ()

    gboolean            gst_buffer_copy_into                (GstBuffer *dest,
                                                             GstBuffer *src,
                                                             GstBufferCopyFlags flags,
                                                             gsize offset,
                                                             gsize size);

Copies the information from `src` into `dest`.

If `dest` already contains memory and `flags` contains GST_BUFFER_COPY_MEMORY, the memory from `src` will be appended to `dest`.

`flags` indicate which fields will be copied.

`dest` : | a destination GstBuffer
`src` : | a source GstBuffer
`flags` : | flags indicating what metadata fields should be copied.
`offset` : | offset to copy from
`size` : | total size to copy. If -1, all data is copied.
Returns : | `TRUE` if the copying succeeded, `FALSE` otherwise.

### gst_buffer_copy_region ()

    GstBuffer *         gst_buffer_copy_region              (GstBuffer *parent,
                                                             GstBufferCopyFlags flags,
                                                             gsize offset,
                                                             gsize size);

Creates a sub-buffer from `parent` at `offset` and `size`. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE. If `offset` equals 0 and `size` equals the total size of `buffer`, the duration and offset end fields are also copied. If not they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE.

MT safe.

`parent` : | a GstBuffer.
`flags` : | the GstBufferCopyFlags
`offset` : | the offset into parent GstBuffer at which the new sub-buffer begins.
`size` : | the size of the new GstBuffer sub-buffer, in bytes.
Returns : | the new GstBuffer or NULL if the arguments were invalid. [transfer full]

### gst_buffer_is_writable()

    #define         gst_buffer_is_writable(buf)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))

Tests if you can safely write to a buffer's metadata or its memory array. It is only safe to change buffer metadata when the current reference is writable, i.e. nobody can see the modifications you will make.

`buf` : | a GstBuffer

### gst_buffer_make_writable()

    #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))

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

`buf` : | a GstBuffer. [transfer full]
Returns : | a writable buffer which may or may not be the same as `buf`. [transfer full]

### gst_buffer_replace ()

    gboolean            gst_buffer_replace                  (GstBuffer **obuf,
                                                             GstBuffer *nbuf);

Modifies a pointer to a GstBuffer to point to a different GstBuffer. 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 is unreffed, the new is reffed).

Either `nbuf` or the GstBuffer pointed to by `obuf` may be NULL.

`obuf` : | pointer to a pointer to a GstBuffer to be replaced. [inout][transfer full]
`nbuf` : | pointer to a GstBuffer that will replace the buffer pointed to by `obuf`. [transfer none][allow-none]
Returns : | TRUE when `obuf` was different from `nbuf`.

### gst_buffer_append ()

    GstBuffer *         gst_buffer_append                   (GstBuffer *buf1,
                                                             GstBuffer *buf2);

Append all the memory from `buf2` to `buf1`. The result buffer will contain a concatenation of the memory of `buf1` and `buf2`.

`buf1` : | the first source GstBuffer to append. [transfer full]
`buf2` : | the second source GstBuffer to append. [transfer full]
Returns : | the new GstBuffer that contains the memory of the two source buffers. [transfer full]

### gst_buffer_append_region ()

    GstBuffer *         gst_buffer_append_region            (GstBuffer *buf1,
                                                             GstBuffer *buf2,
                                                             gssize offset,
                                                             gssize size);

Append `size` bytes at `offset` from `buf2` to `buf1`. The result buffer will contain a concatenation of the memory of `buf1` and the requested region of `buf2`.

`buf1` : | the first source GstBuffer to append. [transfer full]
`buf2` : | the second source GstBuffer to append. [transfer full]
`offset` : | the offset in `buf2`
`size` : | the size or -1 of `buf2`
Returns : | the new GstBuffer that contains the memory of the two source buffers. [transfer full]

### gst_buffer_get_meta ()

    GstMeta *           gst_buffer_get_meta                 (GstBuffer *buffer,
                                                             GType api);

Get the metadata for `api` on buffer. When there is no such metadata, NULL is returned.

`buffer` : | a GstBuffer
`api` : | the GType of an API
Returns : | the metadata for `api` on `buffer`. [transfer none]

### gst_buffer_add_meta ()

    GstMeta *           gst_buffer_add_meta                 (GstBuffer *buffer,
                                                             const GstMetaInfo *info,
                                                             gpointer params);

Add metadata for `info` to `buffer` using the parameters in `params`.

`buffer` : | a GstBuffer
`info` : | a GstMetaInfo
`params` : | params for `info`
Returns : | the metadata for the api in `info` on `buffer`. [transfer none]

### gst_buffer_remove_meta ()

    gboolean            gst_buffer_remove_meta              (GstBuffer *buffer,
                                                             GstMeta *meta);

Remove the metadata for `meta` on `buffer`.

`buffer` : | a GstBuffer
`meta` : | a GstMeta
Returns : | `TRUE` if the metadata existed and was removed, `FALSE` if no such metadata was on `buffer`.

### gst_buffer_iterate_meta ()

    GstMeta *           gst_buffer_iterate_meta             (GstBuffer *buffer,
                                                             gpointer *state);

Retrieve the next GstMeta after `current`. If `state` points to `NULL`, the first metadata is returned.

`state` will be updated with an opage state pointer

`buffer` : | a GstBuffer
`state` : | an opaque state pointer
Returns : | The next GstMeta or `NULL` when there are no more items. [transfer none]

### GstBufferForeachMetaFunc ()

    gboolean            (*GstBufferForeachMetaFunc)         (GstBuffer *buffer,
                                                             GstMeta **meta,
                                                             gpointer user_data);

A function that will be called from `gst_buffer_foreach_meta()`. The `meta` field will point to a the reference of the meta.

`buffer` should not be modified from this callback.

When this function returns `TRUE`, the next meta will be returned. When `FALSE` is returned, `gst_buffer_foreach_meta()` will return.

When `meta` is set to NULL, the item will be removed from the buffer.

`buffer` : | a GstBuffer
`meta` : | a pointer to a GstMeta
`user_data` : | user data passed to `gst_buffer_foreach_meta()`
Returns : | `FALSE` when `gst_buffer_foreach_meta()` should stop

### gst_buffer_foreach_meta ()

    gboolean            gst_buffer_foreach_meta             (GstBuffer *buffer,
                                                             GstBufferForeachMetaFunc func,
                                                             gpointer user_data);

Call `func` with `user_data` for each meta in `buffer`.

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

`buffer` : | a GstBuffer
`func` : | a GstBufferForeachMetaFunc to call. [scope call]
`user_data` : | user data passed to `func`. [closure]
Returns : | `FALSE` when `func` returned `FALSE` for one of the metadata.

## See Also

GstPad, GstMiniObject, GstMemory, GstMeta, GstBufferPool