mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-22 17:51:16 +00:00
501 lines
10 KiB
Text
501 lines
10 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.
|
|
<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_DATA (buffer) = g_alloc (size);
|
|
...
|
|
</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_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 12th, 2004 (0.8.5)
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
#GstBufferPool, #GstPad, #GstData
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GstBuffer ##### -->
|
|
<para>
|
|
The basic structure of a buffer.
|
|
</para>
|
|
|
|
@data_type:
|
|
@data:
|
|
@size:
|
|
@maxsize:
|
|
@timestamp:
|
|
@duration:
|
|
@offset:
|
|
@offset_end:
|
|
@free_data:
|
|
@buffer_private:
|
|
@_gst_reserved:
|
|
|
|
<!-- ##### FUNCTION gst_buffer_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@size:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### ENUM GstBufferFlag ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@GST_BUFFER_READONLY:
|
|
@GST_BUFFER_SUBBUFFER:
|
|
@GST_BUFFER_ORIGINAL:
|
|
@GST_BUFFER_DONTFREE:
|
|
@GST_BUFFER_KEY_UNIT:
|
|
@GST_BUFFER_DONTKEEP:
|
|
@GST_BUFFER_IN_CAPS:
|
|
@GST_BUFFER_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_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_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_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.
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_stamp ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dest:
|
|
@src:
|
|
|
|
|
|
<!-- ##### 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_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.
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@parent:
|
|
@offset:
|
|
@size:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_join ##### -->
|
|
<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_is_span_fast ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@buf1:
|
|
@buf2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_default_free ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@buffer:
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@buffer:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
|
|
<para>
|
|
The name used for tracing memory allocations
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### 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_FREE_DATA_FUNC ##### -->
|
|
<para>
|
|
A function that should be called if the buffer has no more references left.
|
|
Elements that utilize hardware memory could use this to re-queue
|
|
the buffer after it's been unreferenced. If no free_data_func has been
|
|
provided, the default will be used which simply deallocates the memory
|
|
region and the GstBuffer object. Manual implementations that want to
|
|
free their own memory but don't do anything special otherwise are
|
|
suggested to set the GST_BUFFER_DONTFREE flag on the buffer and call the
|
|
default data free function (gst_buffer_default_free()) from their manual
|
|
implementation.
|
|
</para>
|
|
|
|
@buf: the #GstBuffer this function belongs to
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GstBufferFreeDataFunc ##### -->
|
|
<para>
|
|
the type for the GST_BUFFER_FREE_DATA_FUNC
|
|
</para>
|
|
|
|
@buffer: the #GstBuffer on which it will operate, when called
|
|
|
|
|
|
<!-- ##### MACRO GST_BUFFER_PRIVATE ##### -->
|
|
<para>
|
|
Private data for the buffer. This can be used to store a pointer to the
|
|
object that can then be retrieved in something like the BUFFER_FREE_DATA_FUNC.
|
|
</para>
|
|
|
|
@buf: the #GstBuffer this data belongs to
|
|
|
|
|
|
<!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GST_BUFFER_MAXSIZE_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:
|
|
|
|
|
|
<!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@buffer:
|
|
|
|
|