GstBuffer

Name

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

Synopsis


#include <gst/gst.h>


#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)
void        (*GstBufferCopyFunc)            (GstBuffer *srcbuf,
                                             GstBuffer *dstbuf);
void        (*GstBufferFreeFunc)            (GstBuffer *buf);
enum        GstBufferFlags;
struct      GstBuffer;
GstBuffer*  gst_buffer_new                  (void);
GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool);
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,
                                             int count);
void        gst_buffer_unref                (GstBuffer *buffer);
void        gst_buffer_destroy              (GstBuffer *buffer);

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_BUFFER_FLAGS()

#define     GST_BUFFER_FLAGS(buf)

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)

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)

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)

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.


GstBufferCopyFunc ()

void        (*GstBufferCopyFunc)            (GstBuffer *srcbuf,
                                             GstBuffer *dstbuf);

This function is used to copy the buffer contents.

srcbuf :the src buffer
dstbuf :the destination 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,
  GST_BUFFER_FLUSH,
  GST_BUFFER_EOS,
  GST_BUFFER_DISCONTINUOUS,
} 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
GST_BUFFER_FLUSHthis buffer is not related to previous buffers. This flag is mainly used when data in a stream has been skipped
GST_BUFFER_EOSthis buffer is the last one in the stream
GST_BUFFER_DISCONTINUOUSThe buffer has a discontinuity


struct GstBuffer

struct GstBuffer {
  /* 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 */
  guint64 timestamp;
  /* max age */
  guint64 maxage;

  /* pointer to metadata, is really lame right now */
//  GSList *metas;

  /* 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);

Create a new buffer using the specified bufferpool.

pool : the buffer pool to use
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,
                                             int 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

See Also

GstBufferPool, GstPad