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_IS_BUFFER(buf) (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER) |
Check if the object is a buffer.
#define GST_BUFFER_FLAGS(buf) (GST_BUFFER(buf)->flags) |
Get the flags from this buffer.
#define GST_BUFFER_FLAG_IS_SET(buf,flag) (GST_BUFFER_FLAGS(buf) & (1<<(flag))) |
Gives the status of a given flag.
#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.
#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.
#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.
#define GST_BUFFER_COPY_FUNC(buf) (GST_BUFFER(buf)->copy) |
Call the buffer specific copy function on the given buffer.
#define GST_BUFFER_FREE_FUNC(buf) (GST_BUFFER(buf)->free) |
Call the buffer specific free function on the given buffer.
GstBuffer* (*GstBufferCopyFunc) (GstBuffer *srcbuf); |
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, } GstBufferFlags; |
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 */ }; |
GstBuffer* gst_buffer_new_from_pool (GstBufferPool *pool, guint32 offset, guint32 size); |
Create a new buffer using the specified bufferpool, offset and size.
GstBuffer* gst_buffer_copy (GstBuffer *buffer); |
Make a full copy of the give buffer, data and all.
GstBuffer* gst_buffer_create_sub (GstBuffer *parent, guint32 offset, guint32 size); |
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, gint 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.
gboolean gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2); |
Determines whether a gst_buffer_span is free, or requires a memcpy.
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.
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.