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.
Creating a buffer for a video frame
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.
If an element knows what pad you will push the buffer out on, it should use
gst_pad_alloc_buffer() instead to create a buffer. This allows downstream
elements to provide special buffers to write in, like hardware buffers.
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 12th, 2004 (0.8.5)
#GstBufferPool, #GstPad, #GstData
The basic structure of a buffer.
@data_type:
@data:
@size:
@maxsize:
@timestamp:
@duration:
@offset:
@offset_end:
@free_data:
@buffer_private:
@_gst_reserved:
@Returns:
@size:
@Returns:
@GST_BUFFER_READONLY:
@GST_BUFFER_SUBBUFFER:
@GST_BUFFER_ORIGINAL:
@GST_BUFFER_DONTFREE:
@GST_BUFFER_KEY_UNIT:
@GST_BUFFER_DONTKEEP:
@GST_BUFFER_IN_CAPS:
@GST_BUFFER_DELTA_UNIT:
@GST_BUFFER_FLAG_LAST:
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.
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
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 duration in nanoseconds of the data in the buffer.
Value will be GST_CLOCK_TIME_NONE if the duration is unknown.
@buf: a #GstBuffer to get the duration from.
Gets the offset in the source file of the beinning of this buffer.
@buf: a #GstBuffer to get offset of.
Gets the offset in the source file of the end of this buffer.
@buf: a #GstBuffer to get offset of.
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.
@dest:
@src:
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.
Tests if you can safely write data into a buffer's data array.
@buf: a #GstBuffer to check
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.
@parent:
@offset:
@size:
@Returns:
@buf1:
@buf2:
@Returns:
@buf1:
@buf2:
@Returns:
@buf1:
@offset:
@buf2:
@len:
@Returns:
@buf1:
@buf2:
@Returns:
@buffer:
@buffer:
@Returns:
The name used for tracing memory allocations
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.
A function that should be called if the buffer has no more references left.
Elements that utilize hardware memory could use this to re-queue
the buffer after it's been unreferenced. If no free_data_func has been
provided, the default will be used which simply deallocates the memory
region and the GstBuffer object. Manual implementations that want to
free their own memory but don't do anything special otherwise are
suggested to set the GST_BUFFER_DONTFREE flag on the buffer and call the
default data free function (gst_buffer_default_free()) from their manual
implementation.
@buf: the #GstBuffer this function belongs to
the type for the GST_BUFFER_FREE_DATA_FUNC
@buffer: the #GstBuffer on which it will operate, when called
Private data for the buffer. This can be used to store a pointer to the
object that can then be retrieved in something like the BUFFER_FREE_DATA_FUNC.
@buf: the #GstBuffer this data belongs to
Tests if the duration is known.
@buffer: the #GstBuffer to check for the duration
Tests if the timestamp is known.
@buffer: the #GstBuffer to check for the timestamp
@buffer:
@buffer:
@buffer: