gstreamer/docs/gst/tmpl/gstbuffer.sgml

398 lines
6.9 KiB
Text
Raw Normal View History

<!-- ##### 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 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. 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, #GstData
</para>
<!-- ##### MACRO GST_IS_BUFFER ##### -->
<para>
Checks if the object is a buffer.
</para>
@buf: object to check
<!-- ##### MACRO GST_BUFFER ##### -->
<para>
Casts an object to a GstBuffer.
</para>
@buf: object to cast
<!-- ##### 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 #GstBufferFlag.
</para>
@buf: a #GstBuffer to query
@flag: the #GstBufferFlag to check
<!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
<para>
Sets a buffer flag.
</para>
@buf: a #GstBuffer to modify
@flag: the #GstBufferFlag to set
<!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
<para>
Clears a buffer flag.
</para>
@buf: a #GstBuffer to modify
@flag: the #GstBufferFlag to clear
<!-- ##### MACRO GST_BUFFER_DATA ##### -->
<para>
Retrieves a pointer to the data element of this buffer.
</para>
@buf: a #GstBuffer to get data pointer of
<!-- ##### 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_OFFSET ##### -->
<para>
Gets the offset in the source file of this buffer.
</para>
@buf: a #GstBuffer to get offset 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_BUFFERPOOL ##### -->
<para>
Gets the bufferpool for this buffer.
</para>
@buf: a #GstBuffer to get bufferpool of
<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
<para>
Gets the bufferpool private data.
</para>
@buf: a #GstBuffer to get bufferpool's private data of
<!-- ##### MACRO GST_BUFFER_LOCK ##### -->
<para>
Obtains a lock on the object, making serialization possible.
</para>
@buf: a #GstBuffer to lock
<!-- ##### MACRO GST_BUFFER_TRYLOCK ##### -->
<para>
Tries to obtain a lock on the buffer.
If it can't get immediately, will return FALSE.
</para>
@buf: a #GstBuffer to try to lock
<!-- ##### MACRO GST_BUFFER_UNLOCK ##### -->
<para>
Releases a lock on the buffer.
</para>
@buf: a #GstBuffer to unlock
<!-- ##### MACRO GST_BUFFER_PARENT ##### -->
<para>
Gets the parent of this buffer. The parent is set on sub-buffers.
</para>
@buf: a #GstBuffer to get parent of
<!-- ##### MACRO GST_BUFFER_MAXAGE ##### -->
<para>
Gets the maximum age of a buffer.
</para>
@buf: a #GstBuffer to get maximum age 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
<!-- ##### USER_FUNCTION GstBufferCopyFunc ##### -->
<para>
This supplied function is used to copy the buffer contents.
</para>
@srcbuf: a #GstBuffer to copy from
@Returns: a newly allocated #GstBuffer copy of srcbuf
<!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
<para>
This supplied function is called when the buffer data has to be freed.
</para>
@buf: a #GstBuffer to clear the buffer data of
<!-- ##### ENUM GstBufferFlag ##### -->
<para>
This enumeration type describes the flags that can be used for a buffer.
</para>
@GST_BUFFER_READONLY: buffer is read-only
@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
<!-- ##### STRUCT GstBuffer ##### -->
<para>
</para>
@data_type:
@lock:
@data:
@size:
@maxsize:
@offset:
@timestamp:
@maxage:
@parent:
@pool:
@pool_private:
@free:
@copy:
<!-- ##### FUNCTION gst_buffer_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
<para>
</para>
@pool:
@offset:
@size:
@Returns:
<!-- # Unused Parameters # -->
@location:
<!-- ##### 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:
<!-- # Unused Parameters # -->
@buf:
@buf2:
<!-- ##### 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:
<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<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_print_stats ##### -->
<para>
</para>