gstreamer/docs/gst/tmpl/gstbuffer.sgml

<!-- ##### SECTION Title ##### -->
GstBuffer

<!-- ##### SECTION Short_Description ##### -->
Data-passing buffer type, supporting sub-buffers.

<!-- ##### SECTION Long_Description ##### -->
<para>
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. 
</para>
<para>
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.
<example>
<title>Creating a buffer for a video frame</title>
  <programlisting>
  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);
  ...
  </programlisting>
</example>
</para>
<para>
Alternatively, use gst_buffer_new_and_alloc() 
to create a buffer with preallocated data of a given size.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
To efficiently create a smaller buffer out of an existing one, you can
use gst_buffer_create_sub().
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>

<para>
Last reviewed on August 12th, 2004 (0.8.5)
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstBufferPool, #GstPad, #GstData
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GstBuffer ##### -->
<para>
The basic structure of a buffer.
</para>

@data_type: 
@data: 
@size: 
@maxsize: 
@timestamp: 
@duration: 
@offset: 
@offset_end: 
@free_data: 
@buffer_private: 
@_gst_reserved: 

<!-- ##### FUNCTION gst_buffer_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
<para>

</para>

@size: 
@Returns: 


<!-- ##### ENUM GstBufferFlag ##### -->
<para>

</para>

@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: 

<!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
<para>
Gets the flags from this buffer.
</para>

@buf: a #GstBuffer to retrieve the flags from.


<!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
<para>
Gives the status of a given flag of a buffer.
</para>

@buf: a #GstBuffer to query flags of.
@flag: the #GstBufferFlag to check.


<!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
<para>
Sets a buffer flag.
</para>

@buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to set.


<!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
<para>
Clears a buffer flag.
</para>

@buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to clear.


<!-- ##### MACRO gst_buffer_set_data ##### -->
<para>
A convenience function to set the data and size on a buffer
</para>

@buf: The buffer to modify
@data: The data to set on the buffer
@size: The size to set on the buffer


<!-- ##### MACRO GST_BUFFER_DATA ##### -->
<para>
Retrieves a pointer to the data element of this buffer.
</para>

@buf: a #GstBuffer to get data pointer of.
@Returns: the pointer to the actual data contents of the buffer.


<!-- ##### MACRO GST_BUFFER_SIZE ##### -->
<para>
Gets the size of the data in this buffer.
</para>

@buf: a #GstBuffer to get data size of.


<!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
<para>
Gets the maximum size of this buffer.
</para>

@buf: a #GstBuffer to get maximum size of.


<!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
<para>
Gets the timestamp for this buffer.
</para>

@buf: a #GstBuffer to get timestamp of.


<!-- ##### MACRO GST_BUFFER_DURATION ##### -->
<para>
Gets the duration in nanoseconds of the data in the buffer.
Value will be GST_CLOCK_TIME_NONE if the duration is unknown.
</para>

@buf: a #GstBuffer to get the duration from.


<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
<para>
Gets the offset in the source file of the beinning of this buffer.
</para>

@buf: a #GstBuffer to get offset of.


<!-- ##### MACRO GST_BUFFER_OFFSET_END ##### -->
<para>
Gets the offset in the source file of the end of this buffer.
</para>

@buf: a #GstBuffer to get offset of.


<!-- ##### MACRO gst_buffer_ref ##### -->
<para>
Increases the refcount of the given buffer by one.
</para>

@buf: a #GstBuffer to increase the refcount of.


<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
<para>
Increases the refcount of the buffer by the given value. 
</para>

@buf: a #GstBuffer to increase the refcount of.
@c: the value to add to the refcount.


<!-- ##### MACRO gst_buffer_unref ##### -->
<para>
Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
will be freed.
</para>

@buf: a #GstBuffer to unref.


<!-- ##### FUNCTION gst_buffer_stamp ##### -->
<para>

</para>

@dest: 
@src: 


<!-- ##### MACRO gst_buffer_copy ##### -->
<para>
Copies the given buffer using the copy function of the parent GstData structure.
</para>

@buf: a #GstBuffer to copy.
@Returns: a new #GstBuffer copy of the buffer.


<!-- ##### MACRO gst_buffer_is_writable ##### -->
<para>
Tests if you can safely write data into a buffer's data array.
</para>

@buf: a #GstBuffer to check


<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
<para>
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.
</para>

@buf: a #GstBuffer to copy
@Returns: the #GstBuffer that can safely be written to.


<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<para>

</para>

@parent: 
@offset: 
@size: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_join ##### -->
<para>

</para>

@buf1: 
@buf2: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_merge ##### -->
<para>

</para>

@buf1: 
@buf2: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_span ##### -->
<para>

</para>

@buf1: 
@offset: 
@buf2: 
@len: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<para>

</para>

@buf1: 
@buf2: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_default_free ##### -->
<para>

</para>

@buffer: 


<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
<para>

</para>

@buffer: 
@Returns: 


<!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
<para>
The name used for tracing memory allocations
</para>



<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
<para>
Gets a handle to the refcount structure of the buffer.
</para>

@buf: a #GstBuffer to get the refcount structure of.


<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
<para>
Gets the current refcount value of the buffer.
</para>

@buf: a #GstBuffer to get the refcount value of.


<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
<para>
Calls the buffer-specific copy function on the given buffer.
</para>

@buf: a #GstBuffer to copy.


<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
<para>
Calls the buffer-specific free function on the given buffer.
</para>

@buf: a #GstBuffer to free.


<!-- ##### MACRO GST_BUFFER_FREE_DATA_FUNC ##### -->
<para>
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.
</para>

@buf: the #GstBuffer this function belongs to


<!-- ##### USER_FUNCTION GstBufferFreeDataFunc ##### -->
<para>
the type for the GST_BUFFER_FREE_DATA_FUNC
</para>

@buffer: the #GstBuffer on which it will operate, when called


<!-- ##### MACRO GST_BUFFER_PRIVATE ##### -->
<para>
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.
</para>

@buf: the #GstBuffer this data belongs to


<!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
<para>

</para>



<!-- ##### MACRO GST_BUFFER_MAXSIZE_NONE ##### -->
<para>

</para>



<!-- ##### MACRO GST_BUFFER_DURATION_IS_VALID ##### -->
<para>
Tests if the duration is known.
</para>

@buffer: the #GstBuffer to check for the duration


<!-- ##### MACRO GST_BUFFER_TIMESTAMP_IS_VALID ##### -->
<para>
Tests if the timestamp is known.
</para>

@buffer: the #GstBuffer to check for the timestamp


<!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
<para>

</para>

@buffer: 


<!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
<para>

</para>

@buffer: 


<!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
<para>

</para>

@buffer: