GstBuffer

GstBuffer — Data-passing buffer type, supporting sub-buffers.

Synopsis


#include <gst/gst.h>


            GstBuffer;
enum        GstBufferFlag;
#define     GST_BUFFER_FLAGS                (buf)
#define     GST_BUFFER_FLAG_IS_SET          (buf,flag)
#define     GST_BUFFER_FLAG_SET             (buf,flag)
#define     GST_BUFFER_FLAG_UNSET           (buf,flag)
#define     GST_BUFFER_DATA                 (buf)
#define     GST_BUFFER_MALLOCDATA           (buf)
#define     GST_BUFFER_SIZE                 (buf)
#define     GST_BUFFER_TIMESTAMP            (buf)
#define     GST_BUFFER_DURATION             (buf)
#define     GST_BUFFER_CAPS                 (buf)
#define     GST_BUFFER_OFFSET               (buf)
#define     GST_BUFFER_OFFSET_END           (buf)
#define     GST_BUFFER_OFFSET_NONE
#define     GST_BUFFER_DURATION_IS_VALID    (buffer)
#define     GST_BUFFER_TIMESTAMP_IS_VALID   (buffer)
#define     GST_BUFFER_OFFSET_IS_VALID      (buffer)
#define     GST_BUFFER_OFFSET_END_IS_VALID  (buffer)
#define     GST_BUFFER_TRACE_NAME
GstBuffer*  gst_buffer_new                  (void);
GstBuffer*  gst_buffer_new_and_alloc        (guint size);
#define     gst_buffer_ref                  (buf)
#define     gst_buffer_unref                (buf)
#define     gst_buffer_set_data             (buf, data, size)
#define     gst_buffer_copy                 (buf)
#define     gst_buffer_is_writable          (buf)
#define     gst_buffer_make_writable        (buf)
#define     gst_buffer_replace              (obuf,nbuf)
GstCaps*    gst_buffer_get_caps             (GstBuffer *buffer);
void        gst_buffer_set_caps             (GstBuffer *buffer,
                                             GstCaps *caps);
GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                             guint offset,
                                             guint size);
gboolean    gst_buffer_is_span_fast         (GstBuffer *buf1,
                                             GstBuffer *buf2);
GstBuffer*  gst_buffer_span                 (GstBuffer *buf1,
                                             guint32 offset,
                                             GstBuffer *buf2,
                                             guint32 len);
void        gst_buffer_stamp                (GstBuffer *dest,
                                             const GstBuffer *src);
GstBuffer*  gst_buffer_join                 (GstBuffer *buf1,
                                             GstBuffer *buf2);
GstBuffer*  gst_buffer_merge                (GstBuffer *buf1,
                                             GstBuffer *buf2);


Description

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.

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 3. Creating a buffer for a video frame

  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_alloc (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.

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 GstCaps 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.

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 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_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 it a certain GstBufferFlag 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 GstPad).

Buffers usually are freed by unreffing them with gst_buffer_unref(). When the refcount drops to 0, the buffer memory will be freed again.

Last reviewed on September 24th, 2005 (0.9.0)

Details

GstBuffer

typedef struct {
  GstMiniObject		 mini_object;

  /* pointer to data and its size */
  guint8		*data;			/* pointer to buffer data */
  guint			 size;			/* size of buffer data */

  /* timestamp */
  GstClockTime		 timestamp;
  GstClockTime		 duration;

  /* the media type of this buffer */
  GstCaps		*caps;

  /* media specific offset
   * for video frames, this could be the number of frames,
   * for audio data, this could be the number of audio samples,
   * for file data or compressed data, this could be the number of bytes
   * offset_end is the last offset contained in the buffer. The format specifies
   * the meaning of both of them exactly.
   */
  guint64		 offset;
  guint64		 offset_end;

  guint8                *malloc_data;
} GstBuffer;


enum GstBufferFlag

typedef enum {
  GST_BUFFER_FLAG_READONLY   = GST_MINI_OBJECT_FLAG_READONLY,
  GST_BUFFER_FLAG_ORIGINAL   = (GST_MINI_OBJECT_FLAG_LAST << 0),	/* original data, not copied, not currently used  */
  GST_BUFFER_FLAG_PREROLL    = (GST_MINI_OBJECT_FLAG_LAST << 1),	/* sample should not be displayed */
  GST_BUFFER_FLAG_DISCONT    = (GST_MINI_OBJECT_FLAG_LAST << 2),	/* buffer is first after discontinuity in the stream */
  GST_BUFFER_FLAG_IN_CAPS    = (GST_MINI_OBJECT_FLAG_LAST << 3),	/* buffer is also part of caps */
  GST_BUFFER_FLAG_GAP        = (GST_MINI_OBJECT_FLAG_LAST << 4),	/* buffer has been created to fill a gap in the stream */
  GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 5),	/* can't be used as sync point in stream */
  /* padding */
  GST_BUFFER_FLAG_LAST       = (GST_MINI_OBJECT_FLAG_LAST << 8)
} GstBufferFlag;

A set of buffer flags used to describe properties of a GstBuffer.

GST_BUFFER_FLAG_READONLY the buffer is read-only.
GST_BUFFER_FLAG_ORIGINAL buffer is not a copy of another buffer.
GST_BUFFER_FLAG_PREROLL the buffer is part of a preroll and should not be displayed.
GST_BUFFER_FLAG_DISCONT the buffer marks a discontinuity in the stream.
GST_BUFFER_FLAG_IN_CAPS the buffer has been added as a field in a GstCaps.
GST_BUFFER_FLAG_GAP the buffer has been created to fill a gap in the stream.
GST_BUFFER_FLAG_DELTA_UNIT this unit cannot be decoded independently. Since 0.8.5
GST_BUFFER_FLAG_LAST additional flags can be added starting from this flag.

GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

Gets the GstBufferFlag flags from this buffer.

buf : a GstBuffer to retrieve the flags from.

GST_BUFFER_FLAG_IS_SET()

#define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)

Gives the status of a given flag of a buffer.

buf : a GstBuffer to query flags of.
flag : the GstBufferFlag to check.

GST_BUFFER_FLAG_SET()

#define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)

Sets a buffer flag.

buf : a GstBuffer to modify flags of.
flag : the GstBufferFlag to set.

GST_BUFFER_FLAG_UNSET()

#define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)

Clears a buffer flag.

buf : a GstBuffer to modify flags of.
flag : the GstBufferFlag to clear.

GST_BUFFER_DATA()

#define GST_BUFFER_DATA(buf)			(GST_BUFFER_CAST(buf)->data)

Retrieves a pointer to the data element of this buffer.

buf : a GstBuffer to get data pointer of.

GST_BUFFER_MALLOCDATA()

#define GST_BUFFER_MALLOCDATA(buf)		(GST_BUFFER_CAST(buf)->malloc_data)

If the buffers data should be automatically freed by buffer management at the end of the buffers lifecycle, also set the data to the mallocdata field.

buf : a GstBuffer to get access to the malloc_data field

GST_BUFFER_SIZE()

#define GST_BUFFER_SIZE(buf)			(GST_BUFFER_CAST(buf)->size)

Gets the size of the data in this buffer.

buf : a GstBuffer to get data size of.

GST_BUFFER_TIMESTAMP()

#define GST_BUFFER_TIMESTAMP(buf)		(GST_BUFFER_CAST(buf)->timestamp)

Gets the timestamp for this buffer.

buf : a GstBuffer to get the timestamp of.:

GST_BUFFER_DURATION()

#define GST_BUFFER_DURATION(buf)		(GST_BUFFER_CAST(buf)->duration)

Gets the duration in nanoseconds of the data in the buffer. Value will be GST_CLOCK_TIME_NONE if the duration is unknown.

buf : a GstBuffer to get the duration from.

GST_BUFFER_CAPS()

#define GST_BUFFER_CAPS(buf)			(GST_BUFFER_CAST(buf)->caps)

Gets the caps for this buffer.

buf : a GstBuffer to get the caps of.

GST_BUFFER_OFFSET()

#define GST_BUFFER_OFFSET(buf)			(GST_BUFFER_CAST(buf)->offset)

Gets the offset in the source file of the beginning of this buffer.

buf : a GstBuffer to get the offset of.

GST_BUFFER_OFFSET_END()

#define GST_BUFFER_OFFSET_END(buf)		(GST_BUFFER_CAST(buf)->offset_end)

Gets the offset in the source file of the end of this buffer.

buf : a GstBuffer to get the offset of.

GST_BUFFER_OFFSET_NONE

#define GST_BUFFER_OFFSET_NONE	((guint64)-1)

Constant for no-offset return results.


GST_BUFFER_DURATION_IS_VALID()

#define GST_BUFFER_DURATION_IS_VALID(buffer)	(GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))

Tests if the duration is known.

buffer : the GstBuffer to check for the duration

GST_BUFFER_TIMESTAMP_IS_VALID()

#define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)	(GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))

Tests if the timestamp is known.

buffer : the GstBuffer to check for the timestamp

GST_BUFFER_OFFSET_IS_VALID()

#define GST_BUFFER_OFFSET_IS_VALID(buffer)	(GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the start offset is known.

buffer : the GstBuffer to check for the start offset

GST_BUFFER_OFFSET_END_IS_VALID()

#define GST_BUFFER_OFFSET_END_IS_VALID(buffer)	(GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the end offset is known.

buffer : the GstBuffer to check for the end offset

GST_BUFFER_TRACE_NAME

#define GST_BUFFER_TRACE_NAME		"GstBuffer"

The name used for tracing memory allocations.


gst_buffer_new ()

GstBuffer*  gst_buffer_new                  (void);

Creates a newly allocated buffer without any data.

Returns : the new GstBuffer. MT safe.

gst_buffer_new_and_alloc ()

GstBuffer*  gst_buffer_new_and_alloc        (guint size);

Creates a newly allocated buffer with data of the given size.

size : the size of the new buffer's data.
Returns : the new GstBuffer. MT safe.

gst_buffer_ref()

#define		gst_buffer_ref(buf)		GST_BUFFER_CAST (gst_mini_object_ref (GST_MINI_OBJECT (buf)))

Increases the refcount of the given buffer by one.

buf : a GstBuffer to increase the refcount of.

gst_buffer_unref()

#define		gst_buffer_unref(buf)		gst_mini_object_unref (GST_MINI_OBJECT (buf))

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer will be freed.

buf : a GstBuffer to decrease the refcount of.

gst_buffer_set_data()

#define     gst_buffer_set_data(buf, data, size)

A convenience function to set the data and size on a buffer.

buf : The buffer to modify
data : The data to set on the buffer
size : The size to set on the buffer

gst_buffer_copy()

#define		gst_buffer_copy(buf)		GST_BUFFER_CAST (gst_mini_object_copy (GST_MINI_OBJECT (buf)))

Copies the given buffer using the copy function of the parent GstData structure.

buf : a GstBuffer to copy.

gst_buffer_is_writable()

#define		gst_buffer_is_writable(buf)	gst_mini_object_is_writable (GST_MINI_OBJECT (buf))

Tests if you can safely write data into a buffer's data array.

buf : a GstBuffer to check

gst_buffer_make_writable()

#define		gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT (buf)))

Makes a writable buffer from the given buffer.

buf : a GstBuffer to make writable

gst_buffer_replace()

#define		gst_buffer_replace(obuf,nbuf)	gst_mini_object_replace ((GstMiniObject **)(obuf), GST_MINI_OBJECT (nbuf))

Replaces the data in obuf with the one in nbuf

obuf : a GstBuffer to receive the data
nbuf : a GstBuffer to take the data from

gst_buffer_get_caps ()

GstCaps*    gst_buffer_get_caps             (GstBuffer *buffer);

Gets the media type of the buffer. This can be NULL if there is not media type attached to this buffer or when the media type is the same as the previous received buffer.

buffer : a GstBuffer to get the caps of.
Returns : a reference to the GstCaps, or NULL if there were no caps on this buffer.

gst_buffer_set_caps ()

void        gst_buffer_set_caps             (GstBuffer *buffer,
                                             GstCaps *caps);

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

buffer : a GstBuffer to set the caps of.
caps : a GstCaps to set.

gst_buffer_create_sub ()

GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                             guint offset,
                                             guint size);

Creates a sub-buffer from the parent at a given offset. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp field when the offset is 0, else they are set to _NONE. The duration field of the new buffer are set to GST_CLOCK_TIME_NONE.

parent : a parent GstBuffer to create a subbuffer from.
offset : the offset into parent GstBuffer.
size : the size of the new GstBuffer sub-buffer (with size > 0).
Returns : the new GstBuffer, or NULL if there was an error. MT safe.

gst_buffer_is_span_fast ()

gboolean    gst_buffer_is_span_fast         (GstBuffer *buf1,
                                             GstBuffer *buf2);

Determines whether a gst_buffer_span() can be done without copying the contents, that is, whether the data areas are contiguous.

buf1 : a first source GstBuffer.
buf2 : the second source GstBuffer.
Returns : TRUE if the buffers are contiguous, FALSE if a copy would be required. MT safe.

gst_buffer_span ()

GstBuffer*  gst_buffer_span                 (GstBuffer *buf1,
                                             guint32 offset,
                                             GstBuffer *buf2,
                                             guint32 len);

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.

buf1 : a first source GstBuffer to merge.
offset : the offset in the first buffer from where the new buffer should start.
buf2 : the second source GstBuffer to merge.
len : the total length of the new buffer.
Returns : the new GstBuffer that spans the two source buffers. MT safe.

gst_buffer_stamp ()

void        gst_buffer_stamp                (GstBuffer *dest,
                                             const GstBuffer *src);

Copies additional information (timestamps and offsets) from one buffer to the other.

dest : buffer to stamp
src : buffer to stamp from

gst_buffer_join ()

GstBuffer*  gst_buffer_join                 (GstBuffer *buf1,
                                             GstBuffer *buf2);

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

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

buf1 : a first source GstBuffer to join.
buf2 : the second source GstBuffer to join.
Returns : the new GstBuffer that's the concatenation of the source buffers.

gst_buffer_merge ()

GstBuffer*  gst_buffer_merge                (GstBuffer *buf1,
                                             GstBuffer *buf2);

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 : a first source GstBuffer to merge.
buf2 : the second source GstBuffer to merge.
Returns : the new GstBuffer that's the concatenation of the source buffers.

See Also

GstPad, GstMiniObject