Next: , Previous: GstBin, Up: Top

3 GstBuffer

Data-passing buffer type, supporting sub-buffers.

3.1 Overview

Buffers are the basic unit of data transfer in GStreamer. The <gst-buffer> 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 prematurely.

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. 

     
       GstBuffer *buffer;
       gint size, width, height, bpp;
       ...
       size = width * height * bpp;
       buffer = gst_buffer_new ();
       GST_BUFFER_SIZE (buffer) = size;
       GST_BUFFER_MALLOCDATA (buffer) = g_malloc (size);
       GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
       ...

Alternatively, use gst-buffer-new-and-alloc to create a buffer with preallocated data of a given size.

The data pointed to by the buffer can be retrieved with the gst-buffer-data macro. The size of the data can be found with gst-buffer-size. For buffers of size 0, the data pointer is undefined (usually NULL) and should never be used.

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.

A buffer has a pointer to a <gst-caps> describing the media type of the data in the buffer. Attach caps to the buffer with gst-buffer-set-caps; this is typically done before pushing out a buffer using gst-pad-push so that the downstream element knows the type of the buffer.

A buffer will usually have a timestamp, and a duration, but neither of these are guaranteed (they may be set to <gst-clock-time-none>). Whenever a meaningful value can be given for these, they should be set. The timestamp and duration are measured in nanoseconds (they are <gst-clock-time> values).

A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the <gst-caps> set on it). Either or both can be set to <gst-buffer-offset-none>.

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.

To efficiently create a smaller buffer out of an existing one, you can use gst-buffer-create-sub.

If a plug-in wants to modify the buffer data in-place, it should first obtain a buffer that is safe to modify by using gst-buffer-make-writable. This function is optimized so that a copy will only be made when it is necessary.

A plugin that only wishes to modify the metadata of a buffer, such as the offset, timestamp or caps, should use gst-buffer-make-metadata-writable, which will create a subbuffer of the original buffer to ensure the caller has sole ownership, and not copy the buffer data.

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 if a certain <gst-buffer-flag> is set.

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.

An element should either unref the buffer or push it out on a src pad using gst-pad-push (see <gst-pad>).

Buffers are usually freed by unreffing them with gst-buffer-unref. When the refcount drops to 0, any data pointed to by gst-buffer-mallocdata will also be freed.

Last reviewed on August 11th, 2006 (0.10.10)

3.2 Usage

— Class: <gst-buffer>
— Function: gst-buffer-new   (ret <gst-buffer>)

Creates a newly allocated buffer without any data.

MT safe.

ret
the new <gst-buffer>.
— Function: gst-buffer-make-metadata-writable (self <gst-buffer>)   (ret <gst-buffer>)
— Method: make-metadata-writable

Similar to gst_buffer_make_writable, but does not ensure that the buffer data array is writable. Instead, this just ensures that the returned buffer is solely owned by the caller, by creating a subbuffer of the original buffer if necessary.

After calling this function, buf should not be referenced anymore. The result of this function has guaranteed writable metadata.

buf
a <gst-buffer>
ret
A new <gst-buffer> with writable metadata.
— Function: gst-buffer-get-caps (self <gst-buffer>)   (ret <gst-caps>)
— Method: get-caps

Gets the media type of the buffer. This can be NULL if there is no media type attached to this buffer.

Returns: a reference to the <gst-caps>. unref after usage.

buffer
a <gst-buffer>.
ret
NULL if there were no caps on this buffer.
— Function: gst-buffer-set-caps (self <gst-buffer>) (caps <gst-caps>)
— Method: set-caps

Sets the media type on the buffer. The refcount of the caps will be increased and any previous caps on the buffer will be unreffed.

buffer
a <gst-buffer>.
caps
a <gst-caps>.
— Function: gst-buffer-create-sub (self <gst-buffer>) (offset unsigned-int) (size unsigned-int)   (ret <gst-buffer>)
— Method: create-sub

Creates a sub-buffer from parent at offset and size. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to <gst-clock-time-none> and <gst-buffer-offset-none>. If offset equals 0 and size equals the total size of buffer, the duration and offset end fields are also copied. If not they will be set to <gst-clock-time-none> and <gst-buffer-offset-none>.

MT safe. Returns: the new <gst-buffer>.

parent
a <gst-buffer>.
offset
the offset into parent <gst-buffer> at which the new sub-buffer begins.
size
the size of the new <gst-buffer> sub-buffer, in bytes.
ret
NULL if the arguments were invalid.
— Function: gst-buffer-is-span-fast (self <gst-buffer>) (buf2 <gst-buffer>)   (ret bool)
— Method: is-span-fast

Determines whether a gst-buffer-span can be done without copying the contents, that is, whether the data areas are contiguous sub-buffers of the same buffer.

MT safe.

buf1
the first <gst-buffer>.
buf2
the second <gst-buffer>.
ret
TRUE if the buffers are contiguous, FALSE if a copy would be required.
— Function: gst-buffer-span (self <gst-buffer>) (offset unsigned-int32) (buf2 <gst-buffer>) (len unsigned-int32)   (ret <gst-buffer>)
— Method: span

Creates a new buffer that consists of part of buf1 and buf2. Logically, buf1 and buf2 are concatenated into a single larger buffer, and a new buffer is created at the given offset inside this space, with a given length.

If the two source buffers are children of the same larger buffer, and are contiguous, the new buffer will be a child of the shared parent, and thus no copying is necessary. you can use gst-buffer-is-span-fast to determine if a memcpy will be needed.

MT safe. Returns: the new <gst-buffer> that spans the two source buffers.

buf1
the first source <gst-buffer> to merge.
offset
the offset in the first buffer from where the new buffer should start.
buf2
the second source <gst-buffer> to merge.
len
the total length of the new buffer.
ret
NULL if the arguments are invalid.
— Function: gst-buffer-stamp (self <gst-buffer>) (src <gst-buffer>)
— Method: stamp

‘gst_buffer_stamp’ is deprecated and should not be used in newly-written code. use gst-buffer-copy-metadata instead, it provides more control.

Copies additional information (the timestamp, duration, and offset start and end) from one buffer to the other.

This function does not copy any buffer flags or caps and is equivalent to gst_buffer_copy_metadata(dest, src, GST_BUFFER_COPY_TIMESTAMPS).

dest
buffer to stamp
src
buffer to stamp from
— Function: gst-buffer-join (self <gst-buffer>) (buf2 <gst-buffer>)   (ret <gst-buffer>)
— Method: join

Create a new buffer that is the concatenation of the two source buffers, and unrefs the original source buffers.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

buf1
the first source <gst-buffer>.
buf2
the second source <gst-buffer>.
ret
the new <gst-buffer> which is the concatenation of the source buffers.
— Function: gst-buffer-merge (self <gst-buffer>) (buf2 <gst-buffer>)   (ret <gst-buffer>)
— Method: merge

Create a new buffer that is the concatenation of the two source buffers. The original source buffers will not be modified or unref'd. Make sure you unref the source buffers if they are not used anymore afterwards.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

buf1
the first source <gst-buffer> to merge.
buf2
the second source <gst-buffer> to merge.
ret
the new <gst-buffer> which is the concatenation of the source buffers.