mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-13 11:56:35 +00:00
f4e002ad63
Original commit message from CVS: A commit of pending (small) changes...
308 lines
5.5 KiB
Text
308 lines
5.5 KiB
Text
<!-- ##### 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.
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|