gstreamer/docs/gst/tmpl/gstbuffer.sgml
Wim Taymans fa4df1659f Small updates
Original commit message from CVS:
Small updates
2002-12-19 20:38:51 +00:00

429 lines
9.2 KiB
Text

<!-- ##### 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.
<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>
</para>
<para>
Alternatively, use gst_buffer_new_and_alloc()
to create a buffer with preallocated
data of a given size.
</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>
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 30th, 2002 (0.4.0.1)
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstBufferPool, #GstPad, #GstData
</para>
<!-- ##### MACRO GST_BUFFER ##### -->
<para>
Casts an object to a GstBuffer.
</para>
@buf: an object to cast.
@Returns: the #GstBuffer to which the given object points.
<!-- ##### MACRO GST_IS_BUFFER ##### -->
<para>
Checks if the pointer is a GstBuffer.
</para>
@buf: a pointer to query.
<!-- ##### 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_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_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_OFFSET ##### -->
<para>
Gets the offset in the source file of this buffer.
</para>
@buf: a #GstBuffer to get offset of.
<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
<para>
Gets the bufferpool for this buffer.
</para>
@buf: a #GstBuffer to get the bufferpool of.
@Returns: the #GstBufferPool of this buffer.
<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
<para>
Gets the bufferpool private data.
</para>
@buf: a #GstBuffer to get bufferpool's private data of.
<!-- ##### ENUM GstBufferFlag ##### -->
<para>
A set of buffer flags used to describe properties of a #GstBuffer.
</para>
@GST_BUFFER_READONLY: the buffer is read-only.
@GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
found with the GST_BUFFER_POOL_PRIVATE() macro.
@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.
@GST_BUFFER_DISCONTINUOUS: the buffer is the first one after a discontinuity
in the stream.
@GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
decoded independently of other buffers.
@GST_BUFFER_PREROLL: the buffer should be decoded but not rendered, it is
mainly used to resynchronise the stream.
@GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
<!-- ##### STRUCT GstBuffer ##### -->
<para>
The basic structure of a buffer.
</para>
@data_type:
@data:
@size:
@maxsize:
@timestamp:
@offset:
@pool:
@pool_private:
<!-- ##### FUNCTION gst_buffer_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
<para>
</para>
@size:
@Returns:
<!-- ##### 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
<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
<para>
</para>
@pool:
@offset:
@size:
@Returns:
<!-- ##### FUNCTION gst_buffer_default_free ##### -->
<para>
</para>
@buffer:
<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
<para>
</para>
@buffer:
@Returns:
<!-- ##### 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.
<!-- ##### 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_needs_copy_on_write ##### -->
<para>
Queries if a copy needs to be ade of the buffer in order to safely write
to its data.
</para>
@buf: The buffer to query.
<!-- ##### 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.
<!-- ##### MACRO gst_buffer_free ##### -->
<para>
Frees the given buffer, regardless of the refcount.
It is dangerous to use this function, you should use gst_buffer_unref() instead.
</para>
@buf: a #GstBuffer to free.
<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<para>
</para>
@parent:
@offset:
@size:
@Returns:
<!-- ##### FUNCTION gst_buffer_merge ##### -->
<para>
</para>
@buf1:
@buf2:
@Returns:
<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<para>
</para>
@buf1:
@buf2:
@Returns:
<!-- ##### FUNCTION gst_buffer_span ##### -->
<para>
</para>
@buf1:
@offset:
@buf2:
@len:
@Returns:
<!-- ##### FUNCTION gst_buffer_print_stats ##### -->
<para>
</para>