GstBuffer

Name

GstBuffer -- Data-passing buffer type, supporting sub-buffers and metadata

Synopsis


#include <gst/gst.h>


#define     GST_IS_BUFFER                   (buf)
#define     GST_BUFFER                      (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_OFFSET               (buf)
#define     GST_BUFFER_MAXSIZE              (buf)
#define     GST_BUFFER_TIMESTAMP            (buf)
#define     GST_BUFFER_BUFFERPOOL           (buf)
#define     GST_BUFFER_POOL_PRIVATE         (buf)
#define     GST_BUFFER_LOCK                 (buf)
#define     GST_BUFFER_TRYLOCK              (buf)
#define     GST_BUFFER_UNLOCK               (buf)
#define     GST_BUFFER_PARENT               (buf)
#define     GST_BUFFER_MAXAGE               (buf)
#define     GST_BUFFER_COPY_FUNC            (buf)
#define     GST_BUFFER_FREE_FUNC            (buf)
GstBuffer*  (*GstBufferCopyFunc)            (GstBuffer *srcbuf);
void        (*GstBufferFreeFunc)            (GstBuffer *buf);
enum        GstBufferFlags;
struct      GstBuffer;
GstBuffer*  gst_buffer_new                  (void);
GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool,
                                             guint32 offset,
                                             guint32 size);
GstBuffer*  gst_buffer_copy                 (GstBuffer *buffer);
GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                             guint32 offset,
                                             guint32 size);
GstBuffer*  gst_buffer_append               (GstBuffer *buffer,
                                             GstBuffer *append);
void        gst_buffer_ref                  (GstBuffer *buffer);
void        gst_buffer_ref_by_count         (GstBuffer *buffer,
                                             gint count);
void        gst_buffer_unref                (GstBuffer *buffer);
void        gst_buffer_destroy              (GstBuffer *buffer);
gboolean    gst_buffer_is_span_fast         (GstBuffer *buf1,
                                             GstBuffer *buf2);
GstBuffer*  gst_buffer_merge                (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 GST. The GstBuffer type provides all the state necessary to define a region of memory as part of a stream. Sub-buffer 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. Metadata is supported as a list of pointers to arbitrary metadata.

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.
  GstBuffer *buffer;
  gint size, widht, height, bpp;

  size = width * height * bpp;

  buffer = gst_buffer_new();
  GST_BUFFER_SIZE (buffer) = size;
  GST_BUFFER_DATA (buffer) = g_alloc (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().

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 flag is set.

Buffers usually are freed by unreffing them with gst_buffer_unref(). gst_buffer_destroy() can also be used to effectively destroy the buffer regardless of the refcount (dangerous).

Details

GST_IS_BUFFER()

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

Check if the object is a buffer.

buf :The object to check


GST_BUFFER()

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

Cast an object to a GstBuffer

buf :The object to cast.


GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)		 	(GST_BUFFER(buf)->flags)

Get the flags from this buffer.

buf :GstBuffer to retrieve the flags from


GST_BUFFER_FLAG_IS_SET()

#define GST_BUFFER_FLAG_IS_SET(buf,flag) 	(GST_BUFFER_FLAGS(buf) & (1<<(flag)))

Gives the status of a given flag.

buf :GstBuffer to query
flag :the flag to check


GST_BUFFER_FLAG_SET()

#define GST_BUFFER_FLAG_SET(buf,flag) 		G_STMT_START{ (GST_BUFFER_FLAGS(buf) |= (1<<(flag))); }G_STMT_END

Set a flag in a buffer.

buf :GstBuffer to query
flag :the flag to set


GST_BUFFER_FLAG_UNSET()

#define GST_BUFFER_FLAG_UNSET(buf,flag) 	G_STMT_START{ (GST_BUFFER_FLAGS(buf) &= ~(1<<(flag))); }G_STMT_END

Clear a flag in a buffer.

buf :GstBuffer to modify
flag :the flag 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 :GstBuffer


GST_BUFFER_SIZE()

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

Get the size of the data in this buffer.

buf :GstBuffer


GST_BUFFER_OFFSET()

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

Get the offset in the source file of this buffer.

buf :GstBuffer


GST_BUFFER_MAXSIZE()

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

Gets the maximun size of this buffer.

buf :GstBuffer


GST_BUFFER_TIMESTAMP()

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

Get the timestamp for this buffer.

buf :GstBuffer


GST_BUFFER_BUFFERPOOL()

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

Get the bufferpool for this buffer.

buf :GstBuffer


GST_BUFFER_POOL_PRIVATE()

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

Get the bufferpool private data.

buf :GstBuffer


GST_BUFFER_LOCK()

#define GST_BUFFER_LOCK(buf)	(g_mutex_lock(GST_BUFFER(buf)->lock))

This macro will obtain a lock on the object, making serialization possible.

buf :GstBuffer to lock


GST_BUFFER_TRYLOCK()

#define GST_BUFFER_TRYLOCK(buf)	(g_mutex_trylock(GST_BUFFER(buf)->lock))

This macro will try to obtain a lock on the object, but will return with FALSE if it can't get it immediately.

buf :GstBuffer to try to lock


GST_BUFFER_UNLOCK()

#define GST_BUFFER_UNLOCK(buf)	(g_mutex_unlock(GST_BUFFER(buf)->lock))

This macro releases a lock on the object.

buf :GstBuffer to unlock.


GST_BUFFER_PARENT()

#define GST_BUFFER_PARENT(buf)		(GST_BUFFER(buf)->parent)

Get the parent of this buffer. The parent is set on subbuffers.

buf :GstBuffer to get the parent of.


GST_BUFFER_MAXAGE()

#define GST_BUFFER_MAXAGE(buf)		(GST_BUFFER(buf)->maxage)

Get the maximun age of a buffer.

buf :GstBuffer to get the maxage of.


GST_BUFFER_COPY_FUNC()

#define GST_BUFFER_COPY_FUNC(buf)	(GST_BUFFER(buf)->copy)

Call the buffer specific copy function on the given buffer.

buf :the buffer to copy.


GST_BUFFER_FREE_FUNC()

#define GST_BUFFER_FREE_FUNC(buf)	(GST_BUFFER(buf)->free)

Call the buffer specific free function on the given buffer.

buf :the buffer to free.


GstBufferCopyFunc ()

GstBuffer*  (*GstBufferCopyFunc)            (GstBuffer *srcbuf);

This function is used to copy the buffer contents.

srcbuf :the src buffer
Returns :The copied buffer


GstBufferFreeFunc ()

void        (*GstBufferFreeFunc)            (GstBuffer *buf);

The function called when the buffer data has to be freed

buf :the buffer to clear the buffer data of.


enum GstBufferFlags

typedef enum {
  GST_BUFFER_READONLY,
  GST_BUFFER_ORIGINAL,
  GST_BUFFER_DONTFREE,

} GstBufferFlags;

GST_BUFFER_READONLYthe buffer is read only
GST_BUFFER_ORIGINALthis buffer not a copy
GST_BUFFER_DONTFREEdo not try to free the data when this buffer is unref-ed


struct GstBuffer

struct GstBuffer {
  GstData 		data_type;

  /* locking */
  GMutex 		*lock;

  /* refcounting */
#ifdef HAVE_ATOMIC_H
  atomic_t 		refcount;
#define GST_BUFFER_REFCOUNT(buf)	(atomic_read(&(GST_BUFFER((buf))->refcount)))
#else
  int 			refcount;
#define GST_BUFFER_REFCOUNT(buf)	(GST_BUFFER(buf)->refcount)
#endif

  /* flags */
  guint16 		flags;

  /* pointer to data, its size, and offset in original source if known */
  guchar 		*data;
  guint32 		size;
  guint32 		maxsize;
  guint32 		offset;

  /* timestamp */
  gint64 		timestamp;
  gint64 		maxage;

  /* subbuffer support, who's my parent? */
  GstBuffer 		*parent;

  /* this is a pointer to the buffer pool (if any) */
  GstBufferPool 	*pool;
  gpointer 		pool_private;

  /* utility function pointers */
  GstBufferFreeFunc 	free;		/* free the data associated with the buffer */
  GstBufferCopyFunc 	copy;		/* copy the data from one buffer to another */
};


gst_buffer_new ()

GstBuffer*  gst_buffer_new                  (void);

Create a new buffer.

Returns : new buffer


gst_buffer_new_from_pool ()

GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool,
                                             guint32 offset,
                                             guint32 size);

Create a new buffer using the specified bufferpool, offset and size.

pool : the buffer pool to use
offset : the offset of the new buffer
size : the size of the new buffer
Returns : new buffer


gst_buffer_copy ()

GstBuffer*  gst_buffer_copy                 (GstBuffer *buffer);

Make a full copy of the give buffer, data and all.

buffer : the orignal GstBuffer to make a copy of
Returns : new buffer


gst_buffer_create_sub ()

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

Creates a sub-buffer from the parent at a given offset.

parent : parent buffer
offset : offset into parent buffer
size : size of new subbuffer
Returns : new buffer


gst_buffer_append ()

GstBuffer*  gst_buffer_append               (GstBuffer *buffer,
                                             GstBuffer *append);

Creates a new buffer by appending the data of append to the existing data of buffer.

buffer : a buffer
append : the buffer to append
Returns : new buffer


gst_buffer_ref ()

void        gst_buffer_ref                  (GstBuffer *buffer);

Increment the refcount of this buffer.

buffer : the GstBuffer to reference


gst_buffer_ref_by_count ()

void        gst_buffer_ref_by_count         (GstBuffer *buffer,
                                             gint count);

Increment the refcount of this buffer by the given number.

buffer : the GstBuffer to reference
count : a number


gst_buffer_unref ()

void        gst_buffer_unref                (GstBuffer *buffer);

Decrement the refcount of this buffer. If the refcount is zero, the buffer will be destroyed.

buffer : the GstBuffer to unref


gst_buffer_destroy ()

void        gst_buffer_destroy              (GstBuffer *buffer);

destroy the buffer

buffer : the GstBuffer to destroy


gst_buffer_is_span_fast ()

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

Determines whether a gst_buffer_span is free, or requires a memcpy.

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


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 : first source buffer to merge
buf2 : second source buffer to merge
Returns : new buffer that's the concatenation of the source buffers


gst_buffer_span ()

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

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

buf1 : first source buffer to merge
offset : offset in first buffer to start new buffer
buf2 : second source buffer to merge
len : length of new buffer
Returns : new buffer that spans the two source buffers


gst_buffer_print_stats ()

void        gst_buffer_print_stats          (void);

Print statistics about live buffers.

See Also

GstBufferPool, GstPad, GstData