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_TYPE                 (buf)
#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_LOCK                 (buf)
#define     GST_BUFFER_TRYLOCK              (buf)
#define     GST_BUFFER_UNLOCK               (buf)
enum        GstBufferFlags;
struct      GstBuffer;
GstBuffer*  gst_buffer_new                  (void);
GstBuffer*  gst_buffer_new_from_pool        (GstBufferPool *pool);
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);
void        gst_buffer_add_meta             (GstBuffer *buffer,
                                             GstMeta *meta);
GstMeta*    gst_buffer_get_first_meta       (GstBuffer *buffer);
GSList*     gst_buffer_get_metas            (GstBuffer *buffer);
void        gst_buffer_remove_meta          (GstBuffer *buffer,
                                             GstMeta *meta);

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 nither memory space goes away. Metadata is supported as a list of pointers to arbitrary metadata.

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

#define GST_BUFFER_TYPE(buf)		(GST_BUFFER(buf)->type)

Retrieves the type id of the data in the buffer.

buf :GstBuffer


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)

buf :GstBuffer


GST_BUFFER_TIMESTAMP()

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

Get the timestamp for this buffer.

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.


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

  /* data type of this buffer */
  guint16 type;
  /* 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;
};


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_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


gst_buffer_add_meta ()

void        gst_buffer_add_meta             (GstBuffer *buffer,
                                             GstMeta *meta);

Add the meta data to the buffer.

buffer : the GstBuffer to add the metadata to
meta : the metadata to add to this buffer


gst_buffer_get_first_meta ()

GstMeta*    gst_buffer_get_first_meta       (GstBuffer *buffer);

Get the first metadata from the buffer.

buffer : the GstBuffer to get the metadata from
Returns : the first metadata from the buffer


gst_buffer_get_metas ()

GSList*     gst_buffer_get_metas            (GstBuffer *buffer);

Get the metadatas from the buffer.

buffer : the GstBuffer to get the metadata from
Returns : a GSList of metadata


gst_buffer_remove_meta ()

void        gst_buffer_remove_meta          (GstBuffer *buffer,
                                             GstMeta *meta);

Remove the given metadata from the buffer.

buffer : the GstBuffer to remove the metadata from
meta : the metadata to remove