GstBuffer
<!-- ##### SECTION Short_Description ##### -->
-Data-passing buffer type, supporting sub-buffers and metadata
+Data-passing buffer type, supporting sub-buffers.
<!-- ##### SECTION Long_Description ##### -->
<para>
-Buffers are the basic unit of data transfer in GST. The GstBuffer type
+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-buffer are also supported, allowing a smaller region 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.
+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.
-<programlisting>
+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, widht, height, bpp;
+ gint size, width, height, bpp;
+
+ ...
size = width * height * bpp;
GST_BUFFER_SIZE (buffer) = size;
GST_BUFFER_DATA (buffer) = g_alloc (size);
...
-
-</programlisting>
+ </programlisting>
+</example>
</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().
+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
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 flag is set.
+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().
-gst_buffer_destroy() can also be used to effectively destroy the buffer
-regardless of the refcount (dangerous).
+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 ##### -->
#GstBufferPool, #GstPad, #GstData
</para>
-<!-- ##### MACRO GST_IS_BUFFER ##### -->
+<!-- ##### 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>
-Check if the object is a buffer.
+
</para>
-@buf: The object to check
+@Returns:
-<!-- ##### MACRO GST_BUFFER ##### -->
+<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
<para>
-Cast an object to a GstBuffer
+
</para>
-@buf: The object to cast.
+@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>
-Get the flags from this buffer.
+Gets the flags from this buffer.
</para>
-@buf: GstBuffer to retrieve the flags from
+@buf: a #GstBuffer to retrieve the flags from.
<!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
<para>
-Gives the status of a given flag.
+Gives the status of a given flag of a buffer.
</para>
-@buf: GstBuffer to query
-@flag: the flag to check
+@buf: a #GstBuffer to query flags of.
+@flag: the #GstBufferFlag to check.
<!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
<para>
-Set a flag in a buffer.
+Sets a buffer flag.
</para>
-@buf: GstBuffer to query
-@flag: the flag to set
+@buf: a #GstBuffer to modify flags of.
+@flag: the #GstBufferFlag to set.
<!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
<para>
-Clear a flag in a buffer.
+Clears a buffer flag.
</para>
-@buf: GstBuffer to modify
-@flag: the flag to clear
+@buf: a #GstBuffer to modify flags of.
+@flag: the #GstBufferFlag to clear.
-<!-- ##### MACRO GST_BUFFER_DATA ##### -->
+<!-- ##### MACRO gst_buffer_set_data ##### -->
<para>
-Retrieves a pointer to the data element of this buffer
+A convenience function to set the data and size on a buffer
</para>
-@buf: GstBuffer
+@buf: The buffer to modify
+@data: The data to set on the buffer
+@size: The size to set on the buffer
-<!-- ##### MACRO GST_BUFFER_SIZE ##### -->
+<!-- ##### MACRO GST_BUFFER_DATA ##### -->
<para>
-Get the size of the data in this buffer.
+Retrieves a pointer to the data element of this buffer.
</para>
-@buf: GstBuffer
+@buf: a #GstBuffer to get data pointer of.
+@Returns: the pointer to the actual data contents of the buffer.
-<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
+<!-- ##### MACRO GST_BUFFER_SIZE ##### -->
<para>
-Get the offset in the source file of this buffer.
+Gets the size of the data in this buffer.
</para>
-@buf: GstBuffer
+@buf: a #GstBuffer to get data size of.
<!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
<para>
-Gets the maximun size of this buffer.
+Gets the maximum size of this buffer.
</para>
-@buf: GstBuffer
+@buf: a #GstBuffer to get maximum size of.
<!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
<para>
-Get the timestamp for this buffer.
+Gets the timestamp for this buffer.
</para>
-@buf: GstBuffer
+@buf: a #GstBuffer to get timestamp of.
-<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
+<!-- ##### MACRO GST_BUFFER_DURATION ##### -->
<para>
-Get the bufferpool for this buffer.
+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: GstBuffer
+@buf: a #GstBuffer to get the duration from.
-<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
<para>
-Get the bufferpool private data.
+Gets the offset in the source file of the beinning of this buffer.
</para>
-@buf: GstBuffer
+@buf: a #GstBuffer to get offset of.
-<!-- ##### MACRO GST_BUFFER_LOCK ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_END ##### -->
<para>
-This macro will obtain a lock on the object, making serialization
-possible.
-
+Gets the offset in the source file of the end of this buffer.
</para>
-@buf: GstBuffer to lock
+@buf: a #GstBuffer to get offset of.
-<!-- ##### MACRO GST_BUFFER_TRYLOCK ##### -->
+<!-- ##### MACRO gst_buffer_ref ##### -->
<para>
-This macro will try to obtain a lock on the object, but will return with
-FALSE if it can't get it immediately.
-
+Increases the refcount of the given buffer by one.
</para>
-@buf: GstBuffer to try to lock
+@buf: a #GstBuffer to increase the refcount of.
-<!-- ##### MACRO GST_BUFFER_UNLOCK ##### -->
+<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
<para>
-This macro releases a lock on the object.
+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: GstBuffer to unlock.
+@buf: a #GstBuffer to unref.
-<!-- ##### MACRO GST_BUFFER_PARENT ##### -->
+<!-- ##### FUNCTION gst_buffer_stamp ##### -->
<para>
-Get the parent of this buffer. The parent is set on subbuffers.
+
</para>
-@buf: GstBuffer to get the parent of.
+@dest:
+@src:
-<!-- ##### MACRO GST_BUFFER_MAXAGE ##### -->
+<!-- ##### MACRO gst_buffer_copy ##### -->
<para>
-Get the maximun age of a buffer.
+Copies the given buffer using the copy function of the parent GstData structure.
</para>
-@buf: GstBuffer to get the maxage of.
+@buf: a #GstBuffer to copy.
+@Returns: a new #GstBuffer copy of the buffer.
-<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
+<!-- ##### MACRO gst_buffer_is_writable ##### -->
<para>
-Call the buffer specific copy function on the given buffer.
+
</para>
-@buf: the buffer to copy.
+@buf:
-<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
+<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
<para>
-Call the buffer specific free function on the given buffer.
+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: the buffer to free.
+@buf: a #GstBuffer to copy
+@Returns: the #GstBuffer that can safely be written to.
-<!-- ##### USER_FUNCTION GstBufferCopyFunc ##### -->
+<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<para>
-This function is used to copy the buffer contents.
+
</para>
-@srcbuf: the src buffer
+@parent:
+@offset:
+@size:
@Returns:
-<!-- # Unused Parameters # -->
-@dstbuf: the destination buffer
-<!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
+<!-- ##### FUNCTION gst_buffer_join ##### -->
<para>
-The function called when the buffer data has to be freed
+
</para>
-@buf: the buffer to clear the buffer data of.
+@buf1:
+@buf2:
+@Returns:
-<!-- ##### ENUM GstBufferFlags ##### -->
+<!-- ##### FUNCTION gst_buffer_merge ##### -->
<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
+@buf1:
+@buf2:
+@Returns:
+
-<!-- ##### STRUCT GstBuffer ##### -->
+<!-- ##### FUNCTION gst_buffer_span ##### -->
<para>
</para>
-@data_type:
-@lock:
-@data:
-@size:
-@maxsize:
+@buf1:
@offset:
-@timestamp:
-@maxage:
-@parent:
-@pool:
-@pool_private:
-@free:
+@buf2:
+@len:
+@Returns:
-<!-- ##### FUNCTION gst_buffer_new ##### -->
+
+<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
<para>
</para>
+@buf1:
+@buf2:
@Returns:
-<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
+<!-- ##### FUNCTION gst_buffer_default_free ##### -->
<para>
</para>
-@pool:
-@offset:
-@size:
-@Returns:
-<!-- # Unused Parameters # -->
-@location:
+@buffer:
-<!-- ##### FUNCTION gst_buffer_copy ##### -->
+<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
+<!-- ##### 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>
-@parent:
-@offset:
-@size:
-@Returns:
+@buf: a #GstBuffer to get the refcount structure of.
-<!-- ##### FUNCTION gst_buffer_append ##### -->
+<!-- ##### 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>
-@buffer:
-@append:
-@Returns:
-<!-- # Unused Parameters # -->
-@buf:
-@buf2:
+@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.
-<!-- ##### FUNCTION gst_buffer_ref ##### -->
+<!-- ##### 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:
+@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
-<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
<para>
</para>
-@buffer:
-@count:
-<!-- ##### FUNCTION gst_buffer_unref ##### -->
+<!-- ##### MACRO GST_BUFFER_MAXSIZE_NONE ##### -->
<para>
</para>
-@buffer:
-<!-- ##### FUNCTION gst_buffer_destroy ##### -->
+<!-- ##### 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:
+@buffer: the #GstBuffer to check for the timestamp
-<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
<para>
</para>
-@buf1:
-@buf2:
-@Returns:
+@buffer:
-<!-- ##### FUNCTION gst_buffer_merge ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
<para>
</para>
-@buf1:
-@buf2:
-@Returns:
+@buffer:
-<!-- ##### FUNCTION gst_buffer_span ##### -->
+<!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
<para>
</para>
-@buf1:
-@offset:
-@buf2:
-@len:
-@Returns:
+@buffer:
projects / platform / upstream / gstreamer.git / blobdiff