GstBuffer

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

Synopsis


#include <gst/gst.h>


#define     GST_BUFFER_TRACE_NAME
#define     GST_BUFFER                      (buf)
#define     GST_IS_BUFFER                   (buf)
#define     GST_BUFFER_REFCOUNT             (buf)
#define     GST_BUFFER_REFCOUNT_VALUE       (buf)
#define     GST_BUFFER_COPY_FUNC            (buf)
#define     GST_BUFFER_FREE_FUNC            (buf)
#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_SIZE                 (buf)
#define     GST_BUFFER_MAXSIZE              (buf)
#define     GST_BUFFER_TIMESTAMP            (buf)
#define     GST_BUFFER_OFFSET               (buf)
enum        GstBufferFlag;
struct      GstBuffer;
GstBuffer*  gst_buffer_new                  (void);
GstBuffer*  gst_buffer_new_and_alloc        (guint size);
#define     gst_buffer_set_data             (buf, data, size)
void        gst_buffer_default_free         (GstBuffer *buffer);
GstBuffer*  gst_buffer_default_copy         (GstBuffer *buffer);
#define     gst_buffer_ref                  (buf)
#define     gst_buffer_ref_by_count         (buf,c)
#define     gst_buffer_unref                (buf)
#define     gst_buffer_copy                 (buf)
#define     gst_buffer_copy_on_write        (buf)
GstBuffer*  gst_buffer_create_sub           (GstBuffer *parent,
                                             guint offset,
                                             guint size);
GstBuffer*  gst_buffer_merge                (GstBuffer *buf1,
                                             GstBuffer *buf2);
gboolean    gst_buffer_is_span_fast         (GstBuffer *buf1,
                                             GstBuffer *buf2);
GstBuffer*  gst_buffer_span                 (GstBuffer *buf1,
                                             guint32 offset,
                                             GstBuffer *buf2,
                                             guint32 len);

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.

  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);
  ...

Alternatively, use gst_buffer_new_and_alloc() to create a buffer with preallocated data of a given size.

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

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_copy_on_write(). 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(). Do not use gst_buffer_free() : this function effectively frees the buffer regardless of the refcount, which is dangerous.

Last reviewed on August 30th, 2002 (0.4.0.1)

Details

GST_BUFFER_TRACE_NAME

#define GST_BUFFER_TRACE_NAME		"GstBuffer"

The name used for tracing memory allocations


GST_BUFFER()

#define GST_BUFFER(buf)         		((GstBuffer *)(buf))

Casts an object to a GstBuffer.

buf :an object to cast.
Returns :the GstBuffer to which the given object points.

GST_IS_BUFFER()

#define GST_IS_BUFFER(buf)      		(GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)

Checks if the pointer is a GstBuffer.

buf :a pointer to query.

GST_BUFFER_REFCOUNT()

#define GST_BUFFER_REFCOUNT(buf)		GST_DATA_REFCOUNT(buf)

Gets a handle to the refcount structure of the buffer.

buf :a GstBuffer to get the refcount structure of.

GST_BUFFER_REFCOUNT_VALUE()

#define GST_BUFFER_REFCOUNT_VALUE(buf)		GST_DATA_REFCOUNT_VALUE(buf)

Gets the current refcount value of the buffer.

buf :a GstBuffer to get the refcount value of.

GST_BUFFER_COPY_FUNC()

#define GST_BUFFER_COPY_FUNC(buf)		GST_DATA_COPY_FUNC(buf)

Calls the buffer-specific copy function on the given buffer.

buf :a GstBuffer to copy.

GST_BUFFER_FREE_FUNC()

#define GST_BUFFER_FREE_FUNC(buf)		GST_DATA_FREE_FUNC(buf)

Calls the buffer-specific free function on the given buffer.

buf :a GstBuffer to free.

GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_DATA_FLAGS(buf)

Gets the 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_DATA_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_DATA_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_DATA_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(buf)->data)

Retrieves a pointer to the data element of this buffer.

buf :a GstBuffer to get data pointer of.
Returns :the pointer to the actual data contents of the buffer.

GST_BUFFER_SIZE()

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

Gets the size of the data in this buffer.

buf :a GstBuffer to get data size of.

GST_BUFFER_MAXSIZE()

#define GST_BUFFER_MAXSIZE(buf)			(GST_BUFFER(buf)->maxsize)

Gets the maximum size of this buffer.

buf :a GstBuffer to get maximum size of.

GST_BUFFER_TIMESTAMP()

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

Gets the timestamp for this buffer.

buf :a GstBuffer to get timestamp of.

GST_BUFFER_OFFSET()

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

Gets the offset in the source file of this buffer.

buf :a GstBuffer to get offset of.

enum GstBufferFlag

typedef enum {
  GST_BUFFER_READONLY   = GST_DATA_READONLY,
  GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
  GST_BUFFER_ORIGINAL,
  GST_BUFFER_DONTFREE,
  GST_BUFFER_KEY_UNIT,
  GST_BUFFER_DONTKEEP,
  GST_BUFFER_FLAG_LAST 	= GST_DATA_FLAG_LAST + 8
} GstBufferFlag;

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

GST_BUFFER_READONLYthe buffer is read-only.
GST_BUFFER_SUBBUFFERthe buffer is a subbuffer, the parent buffer can be found with the GST_BUFFER_POOL_PRIVATE() macro.
GST_BUFFER_ORIGINALbuffer is not a copy of another buffer.
GST_BUFFER_DONTFREEdo not try to free the data when this buffer is unreferenced.
GST_BUFFER_KEY_UNITthe buffer holds a key unit, a unit that can be decoded independently of other buffers.
GST_BUFFER_DONTKEEP
GST_BUFFER_FLAG_LASTadditional flags can be added starting from this flag.

struct GstBuffer

struct GstBuffer {

  GstData 		 data_type;

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

  /* timestamp */
  GstClockTime		 timestamp;		
  GstClockTime		 duration;		

  /* 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;

  GstBufferFreeDataFunc  free_data;
  gpointer 		 buffer_private;

  gpointer _gst_reserved[GST_PADDING];
};

The basic structure of a buffer.


gst_buffer_new ()

GstBuffer*  gst_buffer_new                  (void);

Creates a newly allocated buffer without any data.

Returns : the new GstBuffer.

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.

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_default_free ()

void        gst_buffer_default_free         (GstBuffer *buffer);

Frees the memory associated with the buffer including the buffer data, unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL.

buffer : a GstBuffer to free.

gst_buffer_default_copy ()

GstBuffer*  gst_buffer_default_copy         (GstBuffer *buffer);

Make a full newly allocated copy of the given buffer, data and all.

buffer : a GstBuffer to make a copy of.
Returns : the new GstBuffer.

gst_buffer_ref()

#define		gst_buffer_ref(buf)		GST_BUFFER (gst_data_ref (GST_DATA (buf)))

Increases the refcount of the given buffer by one.

buf :a GstBuffer to increase the refcount of.

gst_buffer_ref_by_count()

#define		gst_buffer_ref_by_count(buf,c)	GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))

Increases the refcount of the buffer by the given value.

buf :a GstBuffer to increase the refcount of.
c :the value to add to the refcount.

gst_buffer_unref()

#define		gst_buffer_unref(buf)		gst_data_unref (GST_DATA (buf))

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

buf :a GstBuffer to unref.

gst_buffer_copy()

#define		gst_buffer_copy(buf)		GST_BUFFER (gst_data_copy (GST_DATA (buf)))

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

buf :a GstBuffer to copy.
Returns :a new GstBuffer copy of the buffer.

gst_buffer_copy_on_write()

#define		gst_buffer_copy_on_write(buf)   GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf)))

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.

buf :a GstBuffer to copy
Returns :the GstBuffer that can safely be written to.

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.

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.

Internally is nothing more than a specialized gst_buffer_span(), so the same optimizations can occur.

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.

gst_buffer_is_span_fast ()

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

Determines whether a gst_buffer_span() is free (as in free beer), or requires a memcpy.

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

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.

See Also

GstBufferPool, GstPad, GstData