Buffer


Object Hierarchy:

Object hierarchy for Buffer

Description:

[ Compact ]
public class Buffer : MiniObject

Buffers are the basic unit of data transfer in GStreamer.

They contain the timing and offset along with other arbitrary metadata that is associated with the Memory blocks that the buffer contains.

Buffers are usually created with Buffer. After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

  GstBuffer *buffer;
GstMemory *memory;
gint size, width, height, bpp;
...
size = width * height * bpp;
buffer = gst_buffer_new ();
memory = gst_allocator_alloc (NULL, size, NULL);
gst_buffer_insert_memory (buffer, -1, memory);
...

Alternatively, use Buffer.allocate to create a buffer with preallocated data of a given size.

Buffers can contain a list of Memory objects. You can retrieve how many memory objects with n_memory and you can get a pointer to memory with peek_memory

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are ClockTime values).

The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.

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 preceding CAPS event). Either or both can be set to 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. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer.

To efficiently create a smaller buffer out of an existing one, you can use copy_region. This method tries to share the memory objects between the two buffers.

If a plug-in wants to modify the buffer data or metadata 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.

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 BufferFlags flag is set.

Buffers can be efficiently merged into a larger buffer with append. Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with add_meta. Metadata can be retrieved with get_meta. See also Meta

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

Buffers are usually freed by unreffing them with gst_buffer_unref. When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a BufferPool will be returned to the pool when the refcount drops to 0.

The ParentBufferMeta is a meta which can be attached to a Buffer to hold a reference to another buffer that is only released when the child Buffer is released.

Typically, ParentBufferMeta is used when the child buffer is directly using the Memory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the Memory is available for re-use. (Since 1.6)


Namespace: Gst
Package: gstreamer-1.0

Content:

Static methods:

Creation methods:

Methods:

Fields:

Inherited Members: