GstBuffer Data-passing buffer type, supporting sub-buffers. 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) #GstBufferPool, #GstPad, #GstData Casts an object to a GstBuffer. @buf: an object to cast. @Returns: the #GstBuffer to which the given object points. Checks if the pointer is a GstBuffer. @buf: a pointer to query. Gets a handle to the refcount structure of the buffer. @buf: a #GstBuffer to get the refcount structure of. Gets the current refcount value of the buffer. @buf: a #GstBuffer to get the refcount value of. Calls the buffer-specific copy function on the given buffer. @buf: a #GstBuffer to copy. Calls the buffer-specific free function on the given buffer. @buf: a #GstBuffer to free. Gets the flags from this buffer. @buf: a #GstBuffer to retrieve the flags from. Gives the status of a given flag of a buffer. @buf: a #GstBuffer to query flags of. @flag: the #GstBufferFlag to check. Sets a buffer flag. @buf: a #GstBuffer to modify flags of. @flag: the #GstBufferFlag to set. Clears a buffer flag. @buf: a #GstBuffer to modify flags of. @flag: the #GstBufferFlag to clear. 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. Gets the size of the data in this buffer. @buf: a #GstBuffer to get data size of. Gets the maximum size of this buffer. @buf: a #GstBuffer to get maximum size of. Gets the timestamp for this buffer. @buf: a #GstBuffer to get timestamp of. Gets the offset in the source file of this buffer. @buf: a #GstBuffer to get offset of. Gets the bufferpool for this buffer. @buf: a #GstBuffer to get the bufferpool of. @Returns: the #GstBufferPool of this buffer. Gets the bufferpool private data. @buf: a #GstBuffer to get bufferpool's private data of. 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. The basic structure of a buffer. @data_type: @data: @size: @maxsize: @timestamp: @offset: @pool: @pool_private: @Returns: @size: @Returns: 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 @pool: @offset: @size: @Returns: @buffer: @buffer: @Returns: Increases the refcount of the given buffer by one. @buf: a #GstBuffer to increase the refcount of. 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. Decreases the refcount of the buffer. If the refcount reaches 0, the buffer will be freed. @buf: a #GstBuffer to unref. 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. Queries if a copy needs to be ade of the buffer in order to safely write to its data. @buf: The buffer to query. 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. 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. @parent: @offset: @size: @Returns: @buf1: @buf2: @Returns: @buf1: @buf2: @Returns: @buf1: @offset: @buf2: @len: @Returns: