gstreamer/docs/gst/tmpl/gstbuffer.sgml

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

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

<!-- ##### SECTION Long_Description ##### -->
<para>
Buffers are the basic unit of data transfer in GST.  The GstBuffer type
provides all the state necessary to define a region of memory as part of a
stream.  Sub-buffer 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.  Metadata is supported as a list of
pointers to arbitrary metadata.
</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.
<programlisting>
  GstBuffer *buffer;
  gint size, widht, height, bpp;

  size = width * height * bpp;

  buffer = gst_buffer_new ();
  GST_BUFFER_SIZE (buffer) = size;
  GST_BUFFER_DATA (buffer) = g_alloc (size);
  ...
  
</programlisting>
</para>
<para>
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().
</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>
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 flag is set.
</para>
<para>
Buffers usually are freed by unreffing them with gst_buffer_unref().
gst_buffer_destroy() can also be used to effectively destroy the buffer
regardless of the refcount (dangerous).
</para>

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

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

@buf: GstBuffer to retrieve the flags from


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

@buf: GstBuffer to query
@flag: the flag to check


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

@buf: GstBuffer to query
@flag: the flag to set


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

@buf: GstBuffer to modify
@flag: the flag to clear


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

@buf: GstBuffer


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

@buf: GstBuffer


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

@buf: GstBuffer


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

@buf: GstBuffer


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

@buf: GstBuffer


<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
<para>
Get the bufferpool for this buffer.
</para>

@buf: GstBuffer


<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
<para>
Get the bufferpool private data.
</para>

@buf: GstBuffer


<!-- ##### MACRO GST_BUFFER_LOCK ##### -->
<para>
This macro will obtain a lock on the object, making serialization
possible.

</para>

@buf: GstBuffer to lock


<!-- ##### MACRO GST_BUFFER_TRYLOCK ##### -->
<para>
This macro will try to obtain a lock on the object, but will return with
FALSE if it can't get it immediately.

</para>

@buf: GstBuffer to try to lock


<!-- ##### MACRO GST_BUFFER_UNLOCK ##### -->
<para>
This macro releases a lock on the object.

</para>

@buf: GstBuffer to unlock.


<!-- ##### MACRO GST_BUFFER_PARENT ##### -->
<para>
Get the parent of this buffer. The parent is set on subbuffers.
</para>

@buf: GstBuffer to get the parent of.


<!-- ##### MACRO GST_BUFFER_MAXAGE ##### -->
<para>
Get the maximun age of a buffer.
</para>

@buf: GstBuffer to get the maxage of.


<!-- ##### USER_FUNCTION GstBufferCopyFunc ##### -->
<para>
This function is used to copy the buffer contents.
</para>

@srcbuf: the src buffer
@dstbuf: the destination buffer


<!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
<para>
The function called when the buffer data has to be freed
</para>

@buf: the buffer to clear the buffer data of.


<!-- ##### ENUM GstBufferFlags ##### -->
<para>

</para>

@GST_BUFFER_READONLY: the buffer is read only
@GST_BUFFER_ORIGINAL: this buffer not a copy
@GST_BUFFER_DONTFREE: do not try to free the data when this buffer is unref-ed
@GST_BUFFER_FLUSH: this buffer is not related to previous buffers. This flag is mainly
used when data in a stream has been skipped
@GST_BUFFER_EOS: this buffer is the last one in the stream
@GST_BUFFER_DISCONTINUOUS: The buffer has a discontinuity

<!-- ##### STRUCT GstBuffer ##### -->
<para>

</para>

@lock: 
@data: 
@size: 
@maxsize: 
@offset: 
@timestamp: 
@maxage: 
@parent: 
@pool: 
@pool_private: 
@free: 

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

</para>

@Returns: 


<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
<para>

</para>

@pool: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_copy ##### -->
<para>

</para>

@buffer: 
@Returns: 


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

</para>

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


<!-- ##### FUNCTION gst_buffer_append ##### -->
<para>

</para>

@buffer: 
@append: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_ref ##### -->
<para>

</para>

@buffer: 


<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
<para>

</para>

@buffer: 
@count: 


<!-- ##### FUNCTION gst_buffer_unref ##### -->
<para>

</para>

@buffer: 


<!-- ##### FUNCTION gst_buffer_destroy ##### -->
<para>

</para>

@buffer: