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.
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. The following example creates a buffer that can hold a given
video frame with a given width, height and bits per plane.
GstBuffer *buffer;
gint size, width, height, bpp;
...
size = width * height * bpp;
buffer = gst_buffer_new();
GST_BUFFER_SIZE (buffer) = size;
GST_BUFFER_DATA (buffer) = g_alloc (size);
... |
Alternatively, use gst_buffer_new_and_alloc()
to create a buffer with preallocated
data of a given 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().
If the plug-in wants to modify the buffer in-place, it should first obtain
a buffer that is safe to modify by using gst_buffer_copy_on_write(). This
function is optimized so that a copy will only be made when it is necessary.
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 GstBufferFlag is set.
Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
An element should either unref the buffer or push it out on a src pad
using gst_pad_push() (see GstPad).
Buffers usually are freed by unreffing them with gst_buffer_unref().
Do not use gst_buffer_free() : this function effectively frees the buffer
regardless of the refcount, which is dangerous.
Last reviewed on August 30th, 2002 (0.4.0.1)
Details
GST_BUFFER()
#define GST_BUFFER(buf) ((GstBuffer *)(buf)) |
Casts an object to a GstBuffer.
GST_IS_BUFFER()
#define GST_IS_BUFFER(buf) (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER) |
Checks if the pointer is a GstBuffer.
GST_BUFFER_REFCOUNT()
#define GST_BUFFER_REFCOUNT(buf) GST_DATA_REFCOUNT(buf) |
Gets a handle to the refcount structure of the buffer.
GST_BUFFER_REFCOUNT_VALUE()
#define GST_BUFFER_REFCOUNT_VALUE(buf) GST_DATA_REFCOUNT_VALUE(buf) |
Gets the current refcount value of the buffer.
GST_BUFFER_COPY_FUNC()
#define GST_BUFFER_COPY_FUNC(buf) GST_DATA_COPY_FUNC(buf) |
Calls the buffer-specific copy function on the given buffer.
GST_BUFFER_FREE_FUNC()
#define GST_BUFFER_FREE_FUNC(buf) GST_DATA_FREE_FUNC(buf) |
Calls the buffer-specific free function on the given buffer.
GST_BUFFER_FLAGS()
#define GST_BUFFER_FLAGS(buf) GST_DATA_FLAGS(buf) |
Gets the flags from this buffer.
GST_BUFFER_FLAG_IS_SET()
#define GST_BUFFER_FLAG_IS_SET(buf,flag) GST_DATA_FLAG_IS_SET (buf, flag) |
Gives the status of a given flag of a buffer.
GST_BUFFER_FLAG_SET()
#define GST_BUFFER_FLAG_SET(buf,flag) GST_DATA_FLAG_SET (buf, flag) |
Sets a buffer flag.
GST_BUFFER_FLAG_UNSET()
#define GST_BUFFER_FLAG_UNSET(buf,flag) GST_DATA_FLAG_UNSET (buf, flag) |
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_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_OFFSET()
#define GST_BUFFER_OFFSET(buf) (GST_BUFFER(buf)->offset) |
Gets the offset in the source file of 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.
enum GstBufferFlag
typedef enum {
GST_BUFFER_READONLY = GST_DATA_READONLY,
GST_BUFFER_SUBBUFFER = GST_DATA_FLAG_LAST,
GST_BUFFER_ORIGINAL,
GST_BUFFER_DONTFREE,
GST_BUFFER_DISCONTINUOUS,
GST_BUFFER_KEY_UNIT,
GST_BUFFER_PREROLL,
GST_BUFFER_FLAG_LAST = GST_DATA_FLAG_LAST + 8
} GstBufferFlag; |
A set of buffer flags used to describe properties of a GstBuffer.
struct GstBuffer
struct GstBuffer {
GstData data_type;
/* pointer to data and its size */
guint8 *data; /* pointer to buffer data */
guint size; /* size of buffer data */
guint64 maxsize; /* max size of this buffer */
guint64 timestamp;
guint64 offset;
/* this is a pointer to the buffer pool (if any) */
GstBufferPool *pool;
/* pointer to pool private data of parent buffer in case of a subbuffer */
gpointer pool_private;
}; |
The basic structure of a buffer.
gst_buffer_new ()
Creates a newly allocated buffer without any data.
gst_buffer_new_and_alloc ()
GstBuffer* gst_buffer_new_and_alloc (guint size); |
Creates a newly allocated buffer with data of the given size.
gst_buffer_new_from_pool ()
Creates a newly allocated buffer using the specified buffer pool,
offset and size.
gst_buffer_default_free ()
void gst_buffer_default_free (GstBuffer *buffer); |
Frees the memory associated with the buffer including the buffer data,
unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL.
This function is used by buffer pools.
gst_buffer_default_copy ()
Make a full newly allocated copy of the given buffer, data and all.
This function is used by buffer pools.
gst_buffer_ref()
#define gst_buffer_ref(buf) GST_BUFFER (gst_data_ref (GST_DATA (buf))) |
Increases the refcount of the given buffer by one.
gst_buffer_ref_by_count()
#define gst_buffer_ref_by_count(buf,c) GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c)) |
Increases the refcount of the buffer by the given value.
gst_buffer_unref()
#define gst_buffer_unref(buf) gst_data_unref (GST_DATA (buf)) |
Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
will be freed.
gst_buffer_copy()
#define gst_buffer_copy(buf) GST_BUFFER (gst_data_copy (GST_DATA (buf))) |
Copies the given buffer using the copy function of the parent GstData structure.
gst_buffer_copy_on_write()
#define gst_buffer_copy_on_write(buf) GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf))) |
This function returns a buffer that is safe to write to.
Copy the buffer if the refcount > 1 so that the newly
created buffer can be safely written to.
If the refcount is 1, this function just returns the original buffer.
gst_buffer_free()
#define gst_buffer_free(buf) gst_data_free (GST_DATA (buf)) |
Frees the given buffer, regardless of the refcount.
It is dangerous to use this function, you should use gst_buffer_unref() instead.
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_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_is_span_fast ()
Determines whether a gst_buffer_span() is free (as in free beer),
or requires a memcpy.
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. you can use
gst_buffer_is_span_fast() to determine if a memcpy will be needed.
gst_buffer_print_stats ()
void gst_buffer_print_stats (void); |
Logs statistics about live buffers (using g_log).