GStreamer Library Reference Manual (Core) | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
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).
#define GST_BUFFER_DATA(buf) (GST_BUFFER(buf)->data) |
Retrieves a pointer to the data element of this buffer
#define GST_BUFFER_SIZE(buf) (GST_BUFFER(buf)->size) |
Get the size of the data in this buffer.
#define GST_BUFFER_OFFSET(buf) (GST_BUFFER(buf)->offset) |
Get the offset in the source file of this buffer.
#define GST_BUFFER_MAXSIZE(buf) (GST_BUFFER(buf)->maxsize) |
Gets the maximun size of this buffer.
#define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER(buf)->timestamp) |
Get the timestamp for this buffer.
#define GST_BUFFER_BUFFERPOOL(buf) (GST_BUFFER(buf)->pool) |
Get the bufferpool for this buffer.
#define GST_BUFFER_POOL_PRIVATE(buf) (GST_BUFFER(buf)->pool_private) |
Get the bufferpool private data.
#define GST_BUFFER_LOCK(buf) (g_mutex_lock(GST_BUFFER(buf)->lock)) |
This macro will obtain a lock on the object, making serialization possible.
#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.
#define GST_BUFFER_UNLOCK(buf) (g_mutex_unlock(GST_BUFFER(buf)->lock)) |
This macro releases a lock on the object.
#define GST_BUFFER_PARENT(buf) (GST_BUFFER(buf)->parent) |
Get the parent of this buffer. The parent is set on subbuffers.
#define GST_BUFFER_MAXAGE(buf) (GST_BUFFER(buf)->maxage) |
Get the maximun age of a buffer.
void (*GstBufferCopyFunc) (GstBuffer *srcbuf, GstBuffer *dstbuf); |
This function is used to copy the buffer contents.
void (*GstBufferFreeFunc) (GstBuffer *buf); |
The function called when the buffer data has to be freed
typedef enum { GST_BUFFER_READONLY, GST_BUFFER_ORIGINAL, GST_BUFFER_DONTFREE, GST_BUFFER_FLUSH, GST_BUFFER_EOS, GST_BUFFER_DISCONTINUOUS, } GstBufferFlags; |
GST_BUFFER_READONLY | the buffer is read only |
GST_BUFFER_ORIGINAL | this buffer not a copy |
GST_BUFFER_DONTFREE | do not try to free the data when this buffer is unref-ed |
GST_BUFFER_FLUSH | this buffer is not related to previous buffers. This flag is mainly used when data in a stream has been skipped |
GST_BUFFER_EOS | this buffer is the last one in the stream |
GST_BUFFER_DISCONTINUOUS | The buffer has a discontinuity |
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 }; |
GstBuffer* gst_buffer_new_from_pool (GstBufferPool *pool); |
Create a new buffer using the specified bufferpool.
GstBuffer* gst_buffer_copy (GstBuffer *buffer); |
Make a full copy of the give buffer, data and all.
GstBuffer* gst_buffer_create_sub (GstBuffer *parent, |
Creates a sub-buffer from the parent at a given offset.
GstBuffer* gst_buffer_append (GstBuffer *buffer, GstBuffer *append); |
Creates a new buffer by appending the data of append to the existing data of buffer.
void gst_buffer_ref_by_count (GstBuffer *buffer, int count); |
Increment the refcount of this buffer by the given number.
void gst_buffer_unref (GstBuffer *buffer); |
Decrement the refcount of this buffer. If the refcount is zero, the buffer will be destroyed.