## GstBuffer

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

## Synopsis

    #include <gst/gst.h>

    #define     GST_BUFFER                      (buf)
    #define     GST_IS_BUFFER                   (buf)
    #define     GST_BUFFER_REFCOUNT             (buf)
    #define     GST_BUFFER_REFCOUNT_VALUE       (buf)
    #define     GST_BUFFER_COPY_FUNC            (buf)
    #define     GST_BUFFER_FREE_FUNC            (buf)
    #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_SIZE                 (buf)
    #define     GST_BUFFER_MAXSIZE              (buf)
    #define     GST_BUFFER_TIMESTAMP            (buf)
    #define     GST_BUFFER_OFFSET               (buf)
    #define     GST_BUFFER_BUFFERPOOL           (buf)
    #define     GST_BUFFER_POOL_PRIVATE         (buf)
    enum        GstBufferFlag;
    struct      GstBuffer;
    GstBuffer*  gst_buffer_new                  (void);
    GstBuffer*  gst_buffer_new_and_alloc        (guint size);
    #define     gst_buffer_set_data             (buf, data, size)
    GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool,
                                                 guint64 offset,
                                                 guint size);
    void        gst_buffer_default_free         (GstBuffer *buffer);
    GstBuffer*  gst_buffer_default_copy         (GstBuffer *buffer);
    #define     gst_buffer_ref                  (buf)
    #define     gst_buffer_ref_by_count         (buf,c)
    #define     gst_buffer_unref                (buf)
    #define     gst_buffer_copy                 (buf)
    #define     gst_buffer_copy_on_write        (buf)
    #define     gst_buffer_free                 (buf)
    GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                                 guint offset,
                                                 guint size);
    GstBuffer*  gst_buffer_merge                (GstBuffer *buf1,
                                                 GstBuffer *buf2);
    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_print_stats          (void);

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

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.

      GstBuffer *buffer;
      gint size, width, height, bpp;

      ...

      size = width * height * bpp;

      buffer = gst_buffer_new();
      GST_BUFFER_SIZE (buffer) = size;
      GST_BUFFER_DATA (buffer) = g_alloc (size);
      ...

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

GstBuffers can also be created from a GstBufferPool with gst_buffer_new_from_pool(). The bufferpool can be obtained from a peer element with gst_pad_get_bufferpool().

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 the plug-in wants to modify the buffer in-place, it should first obtain a buffer that is safe to modify by using gst_buffer_copy_on_write(). 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 it 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 usually are freed by unreffing them with gst_buffer_unref(). Do not use gst_buffer_free() : this function effectively frees the buffer regardless of the refcount, which is dangerous.

Last reviewed on August 30th, 2002 (0.4.0.1)

## Details

### GST_BUFFER()

    #define GST_BUFFER(buf)         		((GstBuffer *)(buf))

Casts an object to a GstBuffer.

`buf` : | an object to cast.
Returns : | the GstBuffer to which the given object points.

### GST_IS_BUFFER()

    #define GST_IS_BUFFER(buf)      		(GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)

Checks if the pointer is a GstBuffer.

`buf` : | a pointer to query.

### GST_BUFFER_REFCOUNT()

    #define GST_BUFFER_REFCOUNT(buf)		GST_DATA_REFCOUNT(buf)

Gets a handle to the refcount structure of the buffer.

`buf` : | a GstBuffer to get the refcount structure of.

### GST_BUFFER_REFCOUNT_VALUE()

    #define GST_BUFFER_REFCOUNT_VALUE(buf)		GST_DATA_REFCOUNT_VALUE(buf)

Gets the current refcount value of the buffer.

`buf` : | a GstBuffer to get the refcount value of.

### GST_BUFFER_COPY_FUNC()

    #define GST_BUFFER_COPY_FUNC(buf)		GST_DATA_COPY_FUNC(buf)

Calls the buffer-specific copy function on the given buffer.

`buf` : | a GstBuffer to copy.

### GST_BUFFER_FREE_FUNC()

    #define GST_BUFFER_FREE_FUNC(buf)		GST_DATA_FREE_FUNC(buf)

Calls the buffer-specific free function on the given buffer.

`buf` : | a GstBuffer to free.

### GST_BUFFER_FLAGS()

    #define GST_BUFFER_FLAGS(buf)                   GST_DATA_FLAGS(buf)

Gets the flags from this buffer.

`buf` : | a GstBuffer to retrieve the flags from.

### GST_BUFFER_FLAG_IS_SET()

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

Gives the status of a given flag of a buffer.

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

### GST_BUFFER_FLAG_SET()

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

Sets a buffer flag.

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

### GST_BUFFER_FLAG_UNSET()

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

Clears a buffer flag.

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

### GST_BUFFER_DATA()

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

Retrieves a pointer to the data element of this buffer.

`buf` : | a GstBuffer to get data pointer of.
Returns : | the pointer to the actual data contents of the buffer.

### GST_BUFFER_SIZE()

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

Gets the size of the data in this buffer.

`buf` : | a GstBuffer to get data size of.

### GST_BUFFER_MAXSIZE()

    #define GST_BUFFER_MAXSIZE(buf)			(GST_BUFFER(buf)->maxsize)

Gets the maximum size of this buffer.

`buf` : | a GstBuffer to get maximum size of.

### GST_BUFFER_TIMESTAMP()

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

Gets the timestamp for this buffer.

`buf` : | a GstBuffer to get timestamp of.

### GST_BUFFER_OFFSET()

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

Gets the offset in the source file of this buffer.

`buf` : | a GstBuffer to get offset of.

### GST_BUFFER_BUFFERPOOL()

    #define GST_BUFFER_BUFFERPOOL(buf)		(GST_BUFFER(buf)->pool)

Gets the bufferpool for this buffer.

`buf` : | a GstBuffer to get the bufferpool of.
Returns : | the GstBufferPool of this buffer.

### GST_BUFFER_POOL_PRIVATE()

    #define GST_BUFFER_POOL_PRIVATE(buf)		(GST_BUFFER(buf)->pool_private)

Gets the bufferpool private data.

`buf` : | a GstBuffer to get bufferpool's private data of.

### enum GstBufferFlag

    typedef enum {
      GST_BUFFER_READONLY   = GST_DATA_READONLY,
      GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
      GST_BUFFER_ORIGINAL,
      GST_BUFFER_DONTFREE,
      GST_BUFFER_DISCONTINUOUS,
      GST_BUFFER_KEY_UNIT,
      GST_BUFFER_PREROLL,
      GST_BUFFER_FLAG_LAST 	= GST_DATA_FLAG_LAST + 8
    } GstBufferFlag;

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

`GST_BUFFER_READONLY` | the buffer is read-only.
`GST_BUFFER_SUBBUFFER` | the buffer is a subbuffer, the parent buffer can be found with the GST_BUFFER_POOL_PRIVATE() macro.
`GST_BUFFER_ORIGINAL` | buffer is not a copy of another buffer.
`GST_BUFFER_DONTFREE` | do not try to free the data when this buffer is unreferenced.
`GST_BUFFER_DISCONTINUOUS` | the buffer is the first one after a discontinuity in the stream.
`GST_BUFFER_KEY_UNIT` | the buffer holds a key unit, a unit that can be decoded independently of other buffers.
`GST_BUFFER_PREROLL` | the buffer should be decoded but not rendered, it is mainly used to resynchronise the stream.
`GST_BUFFER_FLAG_LAST` | additional flags can be added starting from this flag.

### struct GstBuffer

    struct GstBuffer {

      GstData 		 data_type;

      /* pointer to data and its size */
      guint8 		*data;			/* pointer to buffer data */
      guint 		 size;			/* size of buffer data */
      guint64		 maxsize;		/* max size of this buffer */

      /* timestamp */
      guint64		 timestamp;
      /* media specific offset */
      guint64		 offset;

      /* this is a pointer to the buffer pool (if any) */
      GstBufferPool		*pool;
      /* pointer to pool private data of parent buffer in case of a subbuffer */
      gpointer 		 pool_private;
    };

The basic structure of a buffer.

### gst_buffer_new ()

    GstBuffer*  gst_buffer_new                  (void);

Creates a newly allocated buffer without any data.

Returns : | the new GstBuffer.

### gst_buffer_new_and_alloc ()

    GstBuffer*  gst_buffer_new_and_alloc        (guint size);

Creates a newly allocated buffer with data of the given size.

`size` : | the size of the new buffer's data.
Returns : | the new GstBuffer.

### gst_buffer_set_data()

    #define     gst_buffer_set_data(buf, data, size)

A convenience function to set the data and size on a buffer

`buf` : | The buffer to modify
`data` : | The data to set on the buffer
`size` : | The size to set on the buffer

### gst_buffer_new_from_pool ()

    GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool,
                                                 guint64 offset,
                                                 guint size);

Creates a newly allocated buffer using the specified buffer pool, offset and size.

`pool` : | a GstBufferPool to use.
`offset` : | the offset of the new buffer.
`size` : | the size of the new buffer.
Returns : | the new GstBuffer, or NULL if there was an error.

### gst_buffer_default_free ()

    void        gst_buffer_default_free         (GstBuffer *buffer);

Frees the memory associated with the buffer including the buffer data, unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL. This function is used by buffer pools.

`buffer` : | a GstBuffer to free.

### gst_buffer_default_copy ()

    GstBuffer*  gst_buffer_default_copy         (GstBuffer *buffer);

Make a full newly allocated copy of the given buffer, data and all. This function is used by buffer pools.

`buffer` : | a GstBuffer to make a copy of.
Returns : | the new GstBuffer.

### gst_buffer_ref()

    #define		gst_buffer_ref(buf)		GST_BUFFER (gst_data_ref (GST_DATA (buf)))

Increases the refcount of the given buffer by one.

`buf` : | a GstBuffer to increase the refcount of.

### gst_buffer_ref_by_count()

    #define		gst_buffer_ref_by_count(buf,c)	GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))

Increases the refcount of the buffer by the given value.

`buf` : | a GstBuffer to increase the refcount of.
`c` : | the value to add to the refcount.

### gst_buffer_unref()

    #define		gst_buffer_unref(buf)		gst_data_unref (GST_DATA (buf))

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer will be freed.

`buf` : | a GstBuffer to unref.

### gst_buffer_copy()

    #define		gst_buffer_copy(buf)		GST_BUFFER (gst_data_copy (GST_DATA (buf)))

Copies the given buffer using the copy function of the parent GstData structure.

`buf` : | a GstBuffer to copy.
Returns : | a new GstBuffer copy of the buffer.

### gst_buffer_copy_on_write()

    #define		gst_buffer_copy_on_write(buf)   GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf)))

This function returns a buffer that is safe to write to. Copy the buffer if the refcount > 1 so that the newly created buffer can be safely written to. If the refcount is 1, this function just returns the original buffer.

`buf` : | a GstBuffer to copy
Returns : | the GstBuffer that can safely be written to.

### gst_buffer_free()

    #define		gst_buffer_free(buf)		gst_data_free (GST_DATA (buf))

Frees the given buffer, regardless of the refcount. It is dangerous to use this function, you should use gst_buffer_unref() instead.

`buf` : | a GstBuffer to free.

### gst_buffer_create_sub ()

    GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                                 guint offset,
                                                 guint size);

Creates a sub-buffer from the parent at a given offset. This sub-buffer uses the actual memory space of the parent buffer.

`parent` : | a parent GstBuffer to create a subbuffer from.
`offset` : | the offset into parent GstBuffer.
`size` : | the size of the new GstBuffer sub-buffer (with size > 0).
Returns : | the new GstBuffer, or NULL if there was an error.

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

Internally is nothing more than a specialized gst_buffer_span(), so the same optimizations can occur.

`buf1` : | a first source GstBuffer to merge.
`buf2` : | the second source GstBuffer to merge.
Returns : | the new GstBuffer that's the concatenation of the source buffers.

### gst_buffer_is_span_fast ()

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

Determines whether a gst_buffer_span() is free (as in free beer), or requires a memcpy.

`buf1` : | a first source GstBuffer.
`buf2` : | the second source 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.

`buf1` : | a 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.

### gst_buffer_print_stats ()

    void        gst_buffer_print_stats          (void);

Logs statistics about live buffers (using g_log).

## See Also

GstBufferPool, GstPad, GstData