GstBuffer

## GstBuffer GstBuffer — Data-passing buffer type, supporting sub-buffers. |

## Synopsis

    #include <gst/gst.h>

    struct              GstBuffer;
    enum                GstBufferFlag;
    enum                GstBufferCopyFlags;
    #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_DATA                     (buf)
    #define             GST_BUFFER_MALLOCDATA               (buf)
    #define             GST_BUFFER_FREE_FUNC                (buf)
    #define             GST_BUFFER_SIZE                     (buf)
    #define             GST_BUFFER_TIMESTAMP                (buf)
    #define             GST_BUFFER_DURATION                 (buf)
    #define             GST_BUFFER_CAPS                     (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_TIMESTAMP_IS_VALID       (buffer)
    #define             GST_BUFFER_OFFSET_IS_VALID          (buffer)
    #define             GST_BUFFER_OFFSET_END_IS_VALID      (buffer)
    #define             GST_BUFFER_IS_DISCONT               (buffer)
    #define             GST_BUFFER_TRACE_NAME
    GstBuffer *         gst_buffer_new                      (void);
    GstBuffer *         gst_buffer_new_and_alloc            (guint size);
    GstBuffer *         gst_buffer_try_new_and_alloc        (guint size);
    GstBuffer *         gst_buffer_ref                      (GstBuffer *buf);
    void                gst_buffer_unref                    (GstBuffer *buf);
    #define             gst_buffer_set_data                 (buf,
                                                             data,
                                                             size)
    GstBuffer *         gst_buffer_copy                     (const GstBuffer *buf);
    #define             GST_BUFFER_COPY_ALL
    void                gst_buffer_copy_metadata            (GstBuffer *dest,
                                                             const GstBuffer *src,
                                                             GstBufferCopyFlags flags);
    #define             gst_buffer_is_writable              (buf)
    #define             gst_buffer_make_writable            (buf)
    gboolean            gst_buffer_is_metadata_writable     (GstBuffer *buf);
    GstBuffer *         gst_buffer_make_metadata_writable   (GstBuffer *buf);
    void                gst_buffer_replace                  (GstBuffer **obuf,
                                                             GstBuffer *nbuf);
    void                gst_buffer_set_qdata                (GstBuffer *buffer,
                                                             GQuark quark,
                                                             GstStructure *data);
    const GstStructure * gst_buffer_get_qdata               (GstBuffer *buffer,
                                                             GQuark quark);
    GstCaps *           gst_buffer_get_caps                 (GstBuffer *buffer);
    void                gst_buffer_set_caps                 (GstBuffer *buffer,
                                                             GstCaps *caps);
    GstBuffer *         gst_buffer_create_sub               (GstBuffer *parent,
                                                             guint offset,
                                                             guint size);
    gboolean            gst_buffer_is_span_fast             (GstBuffer *buf1,
                                                             GstBuffer *buf2);
    GstBuffer *         gst_buffer_span                     (GstBuffer *buf1,
                                                             guint32 offset,
                                                             GstBuffer *buf2,
                                                             guint32 len);
    void                gst_buffer_stamp                    (GstBuffer *dest,
                                                             const GstBuffer *src);
    GstBuffer *         gst_buffer_join                     (GstBuffer *buf1,
                                                             GstBuffer *buf2);
    GstBuffer *         gst_buffer_merge                    (GstBuffer *buf1,
                                                             GstBuffer *buf2);

## Description

Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type provides all the state necessary to define a region of memory as part of a stream. Sub-buffers are also supported, allowing a smaller region of a buffer to become its own buffer, with mechanisms in place to ensure that neither memory space goes away prematurely.

Buffers are usually created with `gst_buffer_new()`. After a buffer has been created one will typically allocate memory for it and set the size of the buffer data. 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;
    gint size, width, height, bpp;
    ...
    size = width * height * bpp;
    buffer = gst_buffer_new ();
    GST_BUFFER_SIZE (buffer) = size;
    GST_BUFFER_MALLOCDATA (buffer) = g_malloc (size);
    GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
    ...

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

The data pointed to by the buffer can be retrieved with the `GST_BUFFER_DATA()` macro. The size of the data can be found with `GST_BUFFER_SIZE()`. For buffers of size 0, the data pointer is undefined (usually NULL) and should never be used.

If an element knows what pad you will push the buffer out on, it should use `gst_pad_alloc_buffer()` instead to create a buffer. This allows downstream elements to provide special buffers to write in, like hardware buffers.

A buffer has a pointer to a GstCaps describing the media type of the data in the buffer. Attach caps to the buffer with `gst_buffer_set_caps()`; this is typically done before pushing out a buffer using `gst_pad_push()` so that the downstream element knows the type of the buffer.

A buffer will usually have a timestamp, 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 timestamp and duration are measured in nanoseconds (they are GstClockTime values).

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 GstCaps set on it). 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.

To efficiently create a smaller buffer out of an existing one, you can use `gst_buffer_create_sub()`.

If a plug-in wants to modify the buffer data 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.

A plugin that only wishes to modify the metadata of a buffer, such as the offset, timestamp or caps, should use `gst_buffer_make_metadata_writable()`, which will create a subbuffer of the original buffer to ensure the caller has sole ownership, and not copy the buffer data.

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_merge()` and `gst_buffer_span()` if the `gst_buffer_is_span_fast()` function returns TRUE.

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 data pointed to by `GST_BUFFER_MALLOCDATA()` will also be freed.

Last reviewed on August 11th, 2006 (0.10.10)

## Details

### struct GstBuffer

    struct GstBuffer {
      GstMiniObject          mini_object;

      /* pointer to data and its size */
      guint8                *data;
      guint                  size;

      /* timestamp */
      GstClockTime           timestamp;
      GstClockTime           duration;

      /* the media type of this buffer */
      GstCaps               *caps;

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

      guint8                *malloc_data;

      /* ABI Added */
      GFreeFunc              free_func;
      GstBuffer             *parent;
    };

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

GstMiniObject `mini_object`; | the parent structure
guint8 *`data`; | pointer to the buffer data
guint `size`; | size of buffer data
GstClockTime `timestamp`; | timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the timestamp is not known or relevant.
GstClockTime `duration`; | duration in time of the buffer data, can be GST_CLOCK_TIME_NONE when the duration is not known or relevant.
GstCaps *`caps`; | the GstCaps describing the data format in this buffer
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`.
guint8 *`malloc_data`; | a pointer to the allocated memory associated with this buffer. When the buffer is freed, this data will freed with `free_func`.
GFreeFunc `free_func`; | a custom function that will be called with `malloc_data`, defaults to `g_free()`. Since 0.10.22.
GstBuffer *`parent`; | the parent buffer if this is a subbuffer. Since 0.10.26.

### enum GstBufferFlag

    typedef enum {
      GST_BUFFER_FLAG_READONLY   = GST_MINI_OBJECT_FLAG_READONLY,
      GST_BUFFER_FLAG_MEDIA4     = GST_MINI_OBJECT_FLAG_RESERVED1,
      GST_BUFFER_FLAG_PREROLL    = (GST_MINI_OBJECT_FLAG_LAST << 0),
      GST_BUFFER_FLAG_DISCONT    = (GST_MINI_OBJECT_FLAG_LAST << 1),
      GST_BUFFER_FLAG_IN_CAPS    = (GST_MINI_OBJECT_FLAG_LAST << 2),
      GST_BUFFER_FLAG_GAP        = (GST_MINI_OBJECT_FLAG_LAST << 3),
      GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 4),
      GST_BUFFER_FLAG_MEDIA1     = (GST_MINI_OBJECT_FLAG_LAST << 5),
      GST_BUFFER_FLAG_MEDIA2     = (GST_MINI_OBJECT_FLAG_LAST << 6),
      GST_BUFFER_FLAG_MEDIA3     = (GST_MINI_OBJECT_FLAG_LAST << 7),
      GST_BUFFER_FLAG_LAST       = (GST_MINI_OBJECT_FLAG_LAST << 8)
    } GstBufferFlag;

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

`GST_BUFFER_FLAG_READONLY` | the buffer is read-only. This means the data of the buffer should not be modified. The metadata might still be modified.
`GST_BUFFER_FLAG_MEDIA4` | a flag whose use is specific to the caps of the buffer. Since: 0.10.33.
`GST_BUFFER_FLAG_PREROLL` | the buffer is part of a preroll and should not be displayed.
`GST_BUFFER_FLAG_DISCONT` | the buffer marks a discontinuity in the stream. This typically occurs after a seek or a dropped buffer from a live or network source.
`GST_BUFFER_FLAG_IN_CAPS` | the buffer has been added as a field in a GstCaps.
`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_DELTA_UNIT` | this unit cannot be decoded independently.
`GST_BUFFER_FLAG_MEDIA1` | a flag whose use is specific to the caps of the buffer. Since: 0.10.23.
`GST_BUFFER_FLAG_MEDIA2` | a flag whose use is specific to the caps of the buffer. Since: 0.10.23.
`GST_BUFFER_FLAG_MEDIA3` | a flag whose use is specific to the caps of the buffer. Since: 0.10.23.
`GST_BUFFER_FLAG_LAST` | additional flags can be added starting from this flag.

### enum GstBufferCopyFlags

    typedef enum {
      GST_BUFFER_COPY_FLAGS      = (1 << 0),
      GST_BUFFER_COPY_TIMESTAMPS = (1 << 1),
      GST_BUFFER_COPY_CAPS       = (1 << 2),
      GST_BUFFER_COPY_QDATA      = (1 << 3)
    } GstBufferCopyFlags;

A set of flags that can be provided to the `gst_buffer_copy_metadata()` function to specify which metadata fields should be copied.

`GST_BUFFER_COPY_FLAGS` | flag indicating that buffer flags should be copied
`GST_BUFFER_COPY_TIMESTAMPS` | flag indicating that buffer timestamp, duration, offset and offset_end should be copied
`GST_BUFFER_COPY_CAPS` | flag indicating that buffer caps should be copied
`GST_BUFFER_COPY_QDATA` | flag indicating that buffer qdata should be copied (Since 0.10.36)

Since 0.10.13

### 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_DATA()

    #define GST_BUFFER_DATA(buf)                    (GST_BUFFER_CAST(buf)->data)

A pointer to the data element of this buffer.

`buf` : | a GstBuffer.

### GST_BUFFER_MALLOCDATA()

    #define GST_BUFFER_MALLOCDATA(buf)              (GST_BUFFER_CAST(buf)->malloc_data)

A pointer to any data allocated for this buffer using `g_malloc()`. If this is non-NULL, this memory will be freed at the end of the buffer's lifecycle (i.e. when its refcount becomes zero).

`buf` : | a GstBuffer.

### GST_BUFFER_FREE_FUNC()

    #define GST_BUFFER_FREE_FUNC(buf)               (GST_BUFFER_CAST(buf)->free_func)

A pointer to a function that will be called on the buffer's malloc_data when this buffer is finalized. Defaults to `g_free()`.

Note that the free function only affects the buffer's malloc_data; if the buffer's malloc_data is `NULL`, the function will not be called.

`buf` : | a GstBuffer.

Since 0.10.22

### GST_BUFFER_SIZE()

    #define GST_BUFFER_SIZE(buf)                    (GST_BUFFER_CAST(buf)->size)

The size in bytes of the data in this buffer.

`buf` : | a GstBuffer.

### GST_BUFFER_TIMESTAMP()

    #define GST_BUFFER_TIMESTAMP(buf)               (GST_BUFFER_CAST(buf)->timestamp)

The timestamp in nanoseconds (as a GstClockTime) of the data in the buffer. Value will be `GST_CLOCK_TIME_NONE` if the timestamp 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_CAPS()

    #define GST_BUFFER_CAPS(buf)                    (GST_BUFFER_CAST(buf)->caps)

The caps for this buffer.

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

    #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))

Tests if the timestamp 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

Since 0.10.9

### GST_BUFFER_TRACE_NAME

    #define GST_BUFFER_TRACE_NAME           "GstBuffer"

The name used for tracing memory allocations.

### 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_and_alloc ()

    GstBuffer *         gst_buffer_new_and_alloc            (guint size);

Creates a newly allocated buffer with data of the given size. The buffer memory is not cleared. If the requested amount of memory can't be allocated, the program will abort. Use `gst_buffer_try_new_and_alloc()` if you want to handle this case gracefully or have gotten the size to allocate from an untrusted source such as a media stream.

Note that when `size` == 0, the buffer data pointer will be NULL.

MT safe.

`size` : | the size in bytes of the new buffer's data.
Returns : | the new GstBuffer. [transfer full]

### gst_buffer_try_new_and_alloc ()

    GstBuffer *         gst_buffer_try_new_and_alloc        (guint size);

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

Note that when `size` == 0, the buffer data pointer will be NULL.

MT safe.

`size` : | the size in bytes of the new buffer's data.
Returns : | a new GstBuffer, or NULL if the memory couldn't be allocated. [transfer full]

Since 0.10.13

### 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()` and `gst_buffer_is_metadata_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 will be freed. If `GST_BUFFER_MALLOCDATA()` is non-NULL, this pointer will also be freed at this time.

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

### gst_buffer_set_data()

    #define             gst_buffer_set_data(buf, data, size)

A convenience function to set the data and size on a buffer. This will replace any existing data pointer set on this buffer, but will not change `GST_BUFFER_MALLOCDATA()`, if any. Callers should ensure that `GST_BUFFER_MALLOCDATA()` is non-NULL, or should free that and set it to NULL.

No checks are done on the data or size arguments passed.

`buf` : | a GstBuffer
`data` : | The data (a guint8 *) to set on the buffer.
`size` : | The size (in bytes, as a guint) of the data being set.

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

    #define GST_BUFFER_COPY_ALL ((GstBufferCopyFlags) (GST_BUFFER_COPY_FLAGS | GST_BUFFER_COPY_TIMESTAMPS | GST_BUFFER_COPY_CAPS | GST_BUFFER_COPY_QDATA))

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

Since 0.10.13

### gst_buffer_copy_metadata ()

    void                gst_buffer_copy_metadata            (GstBuffer *dest,
                                                             const GstBuffer *src,
                                                             GstBufferCopyFlags flags);

Copies the metadata from `src` into `dest`. The data, size and mallocdata fields are not copied.

`flags` indicate which fields will be copied. Use GST_BUFFER_COPY_ALL to copy all the metadata fields.

This function is typically called from a custom buffer copy function after creating `dest` and setting the data, size, mallocdata.

`dest` : | a destination GstBuffer
`src` : | a source GstBuffer
`flags` : | flags indicating what metadata fields should be copied.

Since 0.10.13

### 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 data into a buffer's data array or validly modify the caps and timestamp metadata. Metadata in a GstBuffer is always writable, but it is only safe to change it when there is only one owner of the buffer - ie, the refcount is 1.

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

    gboolean            gst_buffer_is_metadata_writable     (GstBuffer *buf);

Similar to gst_buffer_is_writable, but this only ensures that the refcount of the buffer is 1, indicating that the caller is the sole owner and can change the buffer metadata, such as caps and timestamps.

`buf` : | a GstBuffer
Returns : | TRUE if the metadata is writable.

### gst_buffer_make_metadata_writable ()

    GstBuffer *         gst_buffer_make_metadata_writable   (GstBuffer *buf);

Similar to gst_buffer_make_writable, but does not ensure that the buffer data array is writable. Instead, this just ensures that the returned buffer is solely owned by the caller, by creating a subbuffer of the original buffer if necessary.

After calling this function, `buf` should not be referenced anymore. The result of this function has guaranteed writable metadata.

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

### gst_buffer_replace ()

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

### gst_buffer_set_qdata ()

    void                gst_buffer_set_qdata                (GstBuffer *buffer,
                                                             GQuark quark,
                                                             GstStructure *data);

Set metadata structure for name quark `quark` to `data`, or remove the existing metadata structure by that name in case `data` is NULL.

Takes ownership of `data`.

`buffer` : | a GstBuffer
`quark` : | name quark of data structure to set or replace
`data` : | a GstStructure to store with the buffer, name must match `quark`. Can be NULL to remove an existing structure. This function takes ownership of the structure passed. [transfer full][allow-none]

Since 0.10.36

### gst_buffer_get_qdata ()

    const GstStructure * gst_buffer_get_qdata               (GstBuffer *buffer,
                                                             GQuark quark);

Get metadata structure for name quark `quark`.

`buffer` : | a GstBuffer
`quark` : | name quark of data structure to find
Returns : | a GstStructure, or NULL if not found. [transfer none]

Since 0.10.36

### gst_buffer_get_caps ()

    GstCaps *           gst_buffer_get_caps                 (GstBuffer *buffer);

Gets the media type of the buffer. This can be NULL if there is no media type attached to this buffer.

`buffer` : | a GstBuffer.
Returns : | a reference to the GstCaps. unref after usage. Returns NULL if there were no caps on this buffer. [transfer full]

### gst_buffer_set_caps ()

    void                gst_buffer_set_caps                 (GstBuffer *buffer,
                                                             GstCaps *caps);

Sets the media type on the buffer. The refcount of the caps will be increased and any previous caps on the buffer will be unreffed.

`buffer` : | a GstBuffer.
`caps` : | a GstCaps. [transfer none]

### gst_buffer_create_sub ()

    GstBuffer *         gst_buffer_create_sub               (GstBuffer *parent,
                                                             guint offset,
                                                             guint 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.
`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_span_fast ()

    gboolean            gst_buffer_is_span_fast             (GstBuffer *buf1,
                                                             GstBuffer *buf2);

Determines whether a `gst_buffer_span()` can be done without copying the contents, that is, whether the data areas are contiguous sub-buffers of the same buffer.

MT safe.

`buf1` : | the first GstBuffer.
`buf2` : | the second GstBuffer.
Returns : | TRUE if the buffers are contiguous, FALSE if a copy would be required.

### gst_buffer_span ()

    GstBuffer *         gst_buffer_span                     (GstBuffer *buf1,
                                                             guint32 offset,
                                                             GstBuffer *buf2,
                                                             guint32 len);

Creates a new buffer that consists of part of buf1 and buf2. Logically, buf1 and buf2 are concatenated into a single larger buffer, and a new buffer is created at the given offset inside this space, with a given length.

If the two source buffers are children of the same larger buffer, and are contiguous, the new buffer will be a child of the shared parent, and thus no copying is necessary. you can use `gst_buffer_is_span_fast()` to determine if a memcpy will be needed.

MT safe.

`buf1` : | the first source GstBuffer to merge.
`offset` : | the offset in the first buffer from where the new buffer should start.
`buf2` : | the second source GstBuffer to merge.
`len` : | the total length of the new buffer.
Returns : | the new GstBuffer that spans the two source buffers, or NULL if the arguments are invalid. [transfer full]

### gst_buffer_stamp ()

    void                gst_buffer_stamp                    (GstBuffer *dest,
                                                             const GstBuffer *src);

### Warning

`gst_buffer_stamp` is deprecated and should not be used in newly-written code. use `gst_buffer_copy_metadata()` instead, it provides more control.

Copies additional information (the timestamp, duration, and offset start and end) from one buffer to the other.

This function does not copy any buffer flags or caps and is equivalent to gst_buffer_copy_metadata(`dest`, `src`, GST_BUFFER_COPY_TIMESTAMPS).

`dest` : | buffer to stamp. [transfer none]
`src` : | buffer to stamp from

### gst_buffer_join ()

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

Create a new buffer that is the concatenation of the two source buffers, and unrefs the original source buffers.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

This is a convenience function for C programmers. See also `gst_buffer_merge()`, which does the same thing without unreffing the input parameters. Language bindings without explicit reference counting should not wrap this function.

`buf1` : | the first source GstBuffer. [transfer full]
`buf2` : | the second source GstBuffer. [transfer full]
Returns : | the new GstBuffer which is the concatenation of the source buffers. [transfer full]

### gst_buffer_merge ()

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

Create a new buffer that is the concatenation of the two source buffers. The original source buffers will not be modified or unref'd. Make sure you unref the source buffers if they are not used anymore afterwards.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

Free-function: gst_buffer_unref

`buf1` : | the first source GstBuffer to merge. [transfer none]
`buf2` : | the second source GstBuffer to merge. [transfer none]
Returns : | the new GstBuffer which is the concatenation of the source buffers. [transfer full]

## See Also

GstPad, GstMiniObject