Description
Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type
provides all the state necessary to define a region of memory as part of a
stream. Sub-buffers 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) |
Checks if the object is a buffer.
GST_BUFFER()
#define GST_BUFFER(buf) ((GstBuffer *)(buf)) |
Casts an object to a GstBuffer.
GST_BUFFER_FLAGS()
#define GST_BUFFER_FLAGS(buf) (GST_BUFFER(buf)->flags) |
Gets the flags from this buffer.
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 GstBufferFlag.
GST_BUFFER_FLAG_SET()
#define GST_BUFFER_FLAG_SET(buf,flag) G_STMT_START{ (GST_BUFFER_FLAGS(buf) |= (1<<(flag))); }G_STMT_END |
Sets a buffer flag.
GST_BUFFER_FLAG_UNSET()
#define GST_BUFFER_FLAG_UNSET(buf,flag) G_STMT_START{ (GST_BUFFER_FLAGS(buf) &= ~(1<<(flag))); }G_STMT_END |
Clears a buffer flag.
GST_BUFFER_DATA()
#define GST_BUFFER_DATA(buf) (GST_BUFFER(buf)->data) |
Retrieves a pointer to the data element of this buffer.
GST_BUFFER_SIZE()
#define GST_BUFFER_SIZE(buf) (GST_BUFFER(buf)->size) |
Gets the size of the data in this buffer.
GST_BUFFER_OFFSET()
#define GST_BUFFER_OFFSET(buf) (GST_BUFFER(buf)->offset) |
Gets the offset in the source file of this buffer.
GST_BUFFER_MAXSIZE()
#define GST_BUFFER_MAXSIZE(buf) (GST_BUFFER(buf)->maxsize) |
Gets the maximum size of this buffer.
GST_BUFFER_TIMESTAMP()
#define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER(buf)->timestamp) |
Gets the timestamp for this buffer.
GST_BUFFER_BUFFERPOOL()
#define GST_BUFFER_BUFFERPOOL(buf) (GST_BUFFER(buf)->pool) |
Gets the bufferpool for this buffer.
GST_BUFFER_POOL_PRIVATE()
#define GST_BUFFER_POOL_PRIVATE(buf) (GST_BUFFER(buf)->pool_private) |
Gets the bufferpool private data.
GST_BUFFER_LOCK()
#define GST_BUFFER_LOCK(buf) (g_mutex_lock(GST_BUFFER(buf)->lock)) |
Obtains a lock on the object, making serialization possible.
GST_BUFFER_TRYLOCK()
#define GST_BUFFER_TRYLOCK(buf) (g_mutex_trylock(GST_BUFFER(buf)->lock)) |
Tries to obtain a lock on the buffer.
If it can't get immediately, will return FALSE.
GST_BUFFER_UNLOCK()
#define GST_BUFFER_UNLOCK(buf) (g_mutex_unlock(GST_BUFFER(buf)->lock)) |
Releases a lock on the buffer.
GST_BUFFER_PARENT()
#define GST_BUFFER_PARENT(buf) (GST_BUFFER(buf)->parent) |
Gets the parent of this buffer. The parent is set on sub-buffers.
GST_BUFFER_MAXAGE()
#define GST_BUFFER_MAXAGE(buf) (GST_BUFFER(buf)->maxage) |
Gets the maximum age of a buffer.
GST_BUFFER_COPY_FUNC()
#define GST_BUFFER_COPY_FUNC(buf) (GST_BUFFER(buf)->copy) |
Calls the buffer-specific copy function on the given buffer.
GST_BUFFER_FREE_FUNC()
#define GST_BUFFER_FREE_FUNC(buf) (GST_BUFFER(buf)->free) |
Calls the buffer-specific free function on the given buffer.
GstBufferCopyFunc ()
This supplied function is used to copy the buffer contents.
GstBufferFreeFunc ()
This supplied function is called when the buffer data has to be freed.
enum GstBufferFlag
typedef enum {
GST_BUFFER_READONLY,
GST_BUFFER_ORIGINAL,
GST_BUFFER_DONTFREE,
GST_BUFFER_DISCONTINOUS,
GST_BUFFER_KEY_UNIT,
GST_BUFFER_PREROLL
} GstBufferFlag; |
This enumeration type describes the flags that can be used for a buffer.
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; /* boolean properties of buffer */
/* pointer to data, its size, and offset in original source if known */
guchar *data;
guint32 size;
guint32 maxsize;
guint32 offset;
/* timestamp */
gint64 timestamp; /* nanoseconds since zero */
gint64 maxage; /* FIXME: not used yet */
/* 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, can override default */
GstBufferFreeFunc free; /* free the data associated with the buffer */
GstBufferCopyFunc copy; /* copy the data from one buffer to another */
}; |
gst_buffer_new ()
Creates a newly allocated buffer.
gst_buffer_new_from_pool ()
Creates a newly allocated buffer using the specified bufferpool, offset and size.
gst_buffer_copy ()
Make a full newly allocated copy of the given buffer, data and all.
gst_buffer_create_sub ()
Creates a sub-buffer from the parent at a given offset.
This sub-buffer uses the actual memory space of the parent buffer.
gst_buffer_append ()
Creates a new buffer by appending the data of second to the
existing data of first. This will grow first if first is unused elsewhere,
or create a newly allocated buffer if it is in use.
second will not be changed.
gst_buffer_ref ()
Increments the reference count of this buffer.
gst_buffer_ref_by_count ()
void gst_buffer_ref_by_count (GstBuffer *buffer,
gint count); |
Increments the reference count of this buffer by the given number.
gst_buffer_unref ()
Decrements the refcount of this buffer. If the refcount is
zero, the buffer will be destroyed.
gst_buffer_destroy ()
Destroys the buffer. Actual data will be retained if DONTFREE is set.
gst_buffer_is_span_fast ()
Determines whether a gst_buffer_span is free (as in free beer),
or requires a memcpy.
gst_buffer_merge ()
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.
gst_buffer_span ()
Creates 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.
gst_buffer_print_stats ()
void gst_buffer_print_stats (void); |
Logs statistics about live buffers (using g_log).