GStreamer Core Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
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)
#define GST_BUFFER(buf) ((GstBuffer *)(buf)) |
Casts an object to a GstBuffer.
buf : | an object to cast. |
Returns : | the GstBuffer to which the given object points. |
#define GST_IS_BUFFER(buf) (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER) |
Checks if the pointer is a GstBuffer.
buf : | a pointer to query. |
#define GST_BUFFER_REFCOUNT(buf) GST_DATA_REFCOUNT(buf) |
Gets a handle to the refcount structure of the buffer.
buf : | a GstBuffer to get the refcount structure of. |
#define GST_BUFFER_REFCOUNT_VALUE(buf) GST_DATA_REFCOUNT_VALUE(buf) |
Gets the current refcount value of the buffer.
buf : | a GstBuffer to get the refcount value of. |
#define GST_BUFFER_COPY_FUNC(buf) GST_DATA_COPY_FUNC(buf) |
Calls the buffer-specific copy function on the given buffer.
buf : | a GstBuffer to copy. |
#define GST_BUFFER_FREE_FUNC(buf) GST_DATA_FREE_FUNC(buf) |
Calls the buffer-specific free function on the given buffer.
buf : | a GstBuffer to free. |
#define GST_BUFFER_FLAGS(buf) GST_DATA_FLAGS(buf) |
Gets the flags from this buffer.
buf : | a GstBuffer to retrieve the flags from. |
#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.
buf : | a GstBuffer to query flags of. |
flag : | the GstBufferFlag to check. |
#define GST_BUFFER_FLAG_SET(buf,flag) GST_DATA_FLAG_SET (buf, flag) |
Sets a buffer flag.
buf : | a GstBuffer to modify flags of. |
flag : | the GstBufferFlag to set. |
#define GST_BUFFER_FLAG_UNSET(buf,flag) GST_DATA_FLAG_UNSET (buf, flag) |
Clears a buffer flag.
buf : | a GstBuffer to modify flags of. |
flag : | the GstBufferFlag to clear. |
#define GST_BUFFER_DATA(buf) (GST_BUFFER(buf)->data) |
Retrieves a pointer to the data element of this buffer.
buf : | a GstBuffer to get data pointer of. |
Returns : | the pointer to the actual data contents of the buffer. |
#define GST_BUFFER_SIZE(buf) (GST_BUFFER(buf)->size) |
Gets the size of the data in this buffer.
buf : | a GstBuffer to get data size of. |
#define GST_BUFFER_MAXSIZE(buf) (GST_BUFFER(buf)->maxsize) |
Gets the maximum size of this buffer.
buf : | a GstBuffer to get maximum size of. |
#define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER(buf)->timestamp) |
Gets the timestamp for this buffer.
buf : | a GstBuffer to get timestamp of. |
#define GST_BUFFER_OFFSET(buf) (GST_BUFFER(buf)->offset) |
Gets the offset in the source file of this buffer.
buf : | a GstBuffer to get offset of. |
#define GST_BUFFER_BUFFERPOOL(buf) (GST_BUFFER(buf)->pool) |
Gets the bufferpool for this buffer.
buf : | a GstBuffer to get the bufferpool of. |
Returns : | the GstBufferPool of this buffer. |
#define GST_BUFFER_POOL_PRIVATE(buf) (GST_BUFFER(buf)->pool_private) |
Gets the bufferpool private data.
buf : | a GstBuffer to get bufferpool's private data of. |
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.
GST_BUFFER_READONLY | the buffer is read-only. |
GST_BUFFER_SUBBUFFER | the buffer is a subbuffer, the parent buffer can be found with the GST_BUFFER_POOL_PRIVATE() macro. |
GST_BUFFER_ORIGINAL | buffer is not a copy of another buffer. |
GST_BUFFER_DONTFREE | do not try to free the data when this buffer is unreferenced. |
GST_BUFFER_DISCONTINUOUS | the buffer is the first one after a discontinuity in the stream. |
GST_BUFFER_KEY_UNIT | the buffer holds a key unit, a unit that can be decoded independently of other buffers. |
GST_BUFFER_PREROLL | the buffer should be decoded but not rendered, it is mainly used to resynchronise the stream. |
GST_BUFFER_FLAG_LAST | additional flags can be added starting from this flag. |
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 */ /* timestamp */ guint64 timestamp; /* media specific offset */ 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.
GstBuffer* gst_buffer_new (void); |
Creates a newly allocated buffer without any data.
Returns : | the new GstBuffer. |
GstBuffer* gst_buffer_new_and_alloc (guint size); |
Creates a newly allocated buffer with data of the given size.
size : | the size of the new buffer's data. |
Returns : | the new GstBuffer. |
#define gst_buffer_set_data(buf, data, size) |
A convenience function to set the data and size on a buffer
buf : | The buffer to modify |
data : | The data to set on the buffer |
size : | The size to set on the buffer |
GstBuffer* gst_buffer_new_from_pool (GstBufferPool *pool, guint64 offset, guint size); |
Creates a newly allocated buffer using the specified buffer pool, offset and size.
pool : | a GstBufferPool to use. |
offset : | the offset of the new buffer. |
size : | the size of the new buffer. |
Returns : | the new GstBuffer, or NULL if there was an error. |
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.
buffer : | a GstBuffer to free. |
GstBuffer* gst_buffer_default_copy (GstBuffer *buffer); |
Make a full newly allocated copy of the given buffer, data and all. This function is used by buffer pools.
buffer : | a GstBuffer to make a copy of. |
Returns : | the new GstBuffer. |
#define gst_buffer_ref(buf) GST_BUFFER (gst_data_ref (GST_DATA (buf))) |
Increases the refcount of the given buffer by one.
buf : | a GstBuffer to increase the refcount of. |
#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.
buf : | a GstBuffer to increase the refcount of. |
c : | the value to add to the refcount. |
#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.
buf : | a GstBuffer to unref. |
#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.
buf : | a GstBuffer to copy. |
Returns : | a new GstBuffer copy of the buffer. |
#define gst_buffer_needs_copy_on_write(buf) GST_BUFFER (gst_data_needs_copy_on_write (GST_DATA (buf))) |
Queries if a copy needs to be ade of the buffer in order to safely write to its data.
buf : | The buffer to query. |
#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.
buf : | a GstBuffer to copy |
Returns : | the GstBuffer that can safely be written to. |
#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.
buf : | a GstBuffer to free. |
GstBuffer* gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size); |
Creates a sub-buffer from the parent at a given offset. This sub-buffer uses the actual memory space of the parent buffer.
parent : | a parent GstBuffer to create a subbuffer from. |
offset : | the offset into parent GstBuffer. |
size : | the size of the new GstBuffer sub-buffer (with size > 0). |
Returns : | the new GstBuffer, or NULL if there was an error. |
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.
buf1 : | a first source GstBuffer to merge. |
buf2 : | the second source GstBuffer to merge. |
Returns : | the new GstBuffer that's the concatenation of the source buffers. |
gboolean gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2); |
Determines whether a gst_buffer_span() is free (as in free beer), or requires a memcpy.
buf1 : | a first source GstBuffer. |
buf2 : | the second source GstBuffer. |
Returns : | TRUE if the buffers are contiguous, FALSE if a copy would be required. |
GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len); |
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.
buf1 : | a first source GstBuffer to merge. |
offset : | the offset in the first buffer from where the new buffer should start. |
buf2 : | the second source GstBuffer to merge. |
len : | the total length of the new buffer. |
Returns : | the new GstBuffer that spans the two source buffers. |