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 */
  guint			 maxsize;		/* max size of this buffer */

  /* timestamp */
  GstClockTime		 timestamp;
  GstClockTime		 duration;

  /* media specific offset
   * for video frames, this could be the number of frames,
   * for audio data, this could be the number of audio samples,
   * for file data or compressed data, this could be the number of bytes
   * offset_end is the last offset contained in the buffer. The format specifies
   * the meaning of both of them exactly.
   */
  guint64		 offset;
  guint64		 offset_end;

  GstBufferFreeDataFunc  free_data;
  gpointer		 buffer_private;

  gpointer _gst_reserved[GST_PADDING];
};

The basic structure of a buffer.

gst_buffer_new ()

GstBuffer*  gst_buffer_new                  (void);

Creates a newly allocated buffer without any data.

gst_buffer_new_and_alloc ()

GstBuffer*  gst_buffer_new_and_alloc        (guint size);

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

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_KEY_UNIT,		/* deprecated, use reverse DELTA_UNIT */
  GST_BUFFER_DONTKEEP,    /* FIXME: is this deprecated ? there is no reference in gstreamer, gst-plugins */
  GST_BUFFER_IN_CAPS,
  GST_BUFFER_DELTA_UNIT,	/* this unit depends on a previous unit */
  GST_BUFFER_FLAG_LAST	= GST_DATA_FLAG_LAST + 8
} GstBufferFlag;

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

GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_DATA_FLAGS(buf)

Gets the flags from this buffer.

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.

GST_BUFFER_FLAG_SET()

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

Sets a buffer flag.

GST_BUFFER_FLAG_UNSET()

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

Clears a buffer flag.

gst_buffer_set_data()

#define     gst_buffer_set_data(buf, data, size)

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

GST_BUFFER_DATA()

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

Retrieves a pointer to the data element of this buffer.

GST_BUFFER_SIZE()

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

Gets the size of the data in this buffer.

GST_BUFFER_MAXSIZE()

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

Gets the maximum size of this buffer.

GST_BUFFER_TIMESTAMP()

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

Gets the timestamp for this buffer.

GST_BUFFER_DURATION()

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

Gets the duration in nanoseconds of the data in the buffer. Value will be GST_CLOCK_TIME_NONE if the duration is unknown.

GST_BUFFER_OFFSET()

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

Gets the offset in the source file of the beinning of this buffer.

GST_BUFFER_OFFSET_END()

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

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

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.

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.

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.

gst_buffer_stamp ()

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

Copies additional information (timestamps and offsets) from one buffer to the other.

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.

gst_buffer_is_writable()

#define		gst_buffer_is_writable(buf)	gst_data_is_writable (GST_DATA (buf))

Tests if you can safely write data into a buffer's data array.

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.

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. This function will copy the offset and timestamp field when the offset is 0, else they are set to _NONE. The duration field of the new buffer are set to GST_CLOCK_TIME_NONE.

gst_buffer_join ()

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

Create a new buffer that is the concatenation of the two source buffers. The original buffers are unreferenced.

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

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.

WARNING: Incorrect use of this function can lead to memory leaks. It is recommended to use gst_buffer_join() instead of this function.

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

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.

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.

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.

gst_buffer_default_copy ()

GstBuffer*  gst_buffer_default_copy         (GstBuffer *buffer);

Make a full newly allocated copy of the given buffer, data and all.

GST_BUFFER_TRACE_NAME

#define GST_BUFFER_TRACE_NAME		"GstBuffer"

The name used for tracing memory allocations

GST_BUFFER_REFCOUNT()

#define GST_BUFFER_REFCOUNT(buf)		GST_DATA_REFCOUNT(buf)

Gets a handle to the refcount structure of the buffer.

GST_BUFFER_REFCOUNT_VALUE()

#define GST_BUFFER_REFCOUNT_VALUE(buf)		GST_DATA_REFCOUNT_VALUE(buf)

Gets the current refcount value of the buffer.

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.

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.

GST_BUFFER_FREE_DATA_FUNC()

#define GST_BUFFER_FREE_DATA_FUNC(buf)          (GST_BUFFER(buf)->free_data)

A function that should be called if the buffer has no more references left. Elements that utilize hardware memory could use this to re-queue the buffer after it's been unreferenced. If no free_data_func has been provided, the default will be used which simply deallocates the memory region and the GstBuffer object. Manual implementations that want to free their own memory but don't do anything special otherwise are suggested to set the GST_BUFFER_DONTFREE flag on the buffer and call the default data free function (gst_buffer_default_free()) from their manual implementation.

GstBufferFreeDataFunc ()

void        (*GstBufferFreeDataFunc)        (GstBuffer *buffer);

the type for the GST_BUFFER_FREE_DATA_FUNC

GST_BUFFER_PRIVATE()

#define GST_BUFFER_PRIVATE(buf)                 (GST_BUFFER(buf)->buffer_private)

Private data for the buffer. This can be used to store a pointer to the object that can then be retrieved in something like the BUFFER_FREE_DATA_FUNC.

GST_BUFFER_OFFSET_NONE

#define GST_BUFFER_OFFSET_NONE	((guint64)-1)

GST_BUFFER_MAXSIZE_NONE

#define GST_BUFFER_MAXSIZE_NONE	((guint)0)

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.

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.

GST_BUFFER_OFFSET_IS_VALID()

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

GST_BUFFER_OFFSET_END_IS_VALID()

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

GST_BUFFER_MAXSIZE_IS_VALID()

#define GST_BUFFER_MAXSIZE_IS_VALID(buffer)	(GST_BUFFER_MAXSIZE (buffer) != GST_BUFFER_MAXSIZE_NONE)