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_MALLOCDATA (buffer) = g_alloc (size);
  GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
  ...
  </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_make_writable().  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>
#GstPad, #GstMiniObject
</para>

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

@mini_object: 
@data: 
@size: 
@timestamp: 
@duration: 
@caps: 
@offset: 
@offset_end: 

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

</para>

@Returns: 


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

</para>

@size: 
@Returns: 


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

</para>

@GST_BUFFER_FLAG_READONLY: 
@GST_BUFFER_FLAG_ORIGINAL: 
@GST_BUFFER_FLAG_PREROLL: 
@GST_BUFFER_FLAG_DISCONT: 
@GST_BUFFER_FLAG_IN_CAPS: 
@GST_BUFFER_FLAG_GAP: 
@GST_BUFFER_FLAG_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_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_unref ##### -->
<para>
Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
will be freed.
</para>

@buf: a #GstBuffer to unref.


<!-- ##### 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_make_writable ##### -->
<para>

</para>

@buf: 


<!-- ##### MACRO gst_buffer_replace ##### -->
<para>

</para>

@obuf: 
@nbuf: 


<!-- ##### FUNCTION gst_buffer_get_caps ##### -->
<para>

</para>

@buffer: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_set_caps ##### -->
<para>

</para>

@buffer: 
@caps: 


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

</para>

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


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

</para>

@buf1: 
@buf2: 
@Returns: 


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

</para>

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


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



<!-- ##### MACRO GST_BUFFER_OFFSET_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: 


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

</para>

@dest: 
@src: 


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

</para>

@buf1: 
@buf2: 
@Returns: 


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

</para>

@buf1: 
@buf2: 
@Returns: