GstBuffer

GstBuffer —

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

Details

GstBuffer

typedef struct {
  GstMiniObject		 mini_object;

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

  /* timestamp */
  GstClockTime		 timestamp;
  GstClockTime		 duration;

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

  /* media specific offset */
  guint64		 offset;
  guint64		 offset_end;

  guint8                *malloc_data;
} GstBuffer;

The structure of a GstBuffer. Use the associated macros to access the public variables.

GstMiniObject mini_object; the parent structure
guint8 *data; pointer to the buffer data
guint size; size of buffer data
GstClockTime timestamp; timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the timestamp is not known or relevant.
GstClockTime duration; duration in time of the buffer data, can be GST_CLOCK_TIME_NONE when the duration is not known or relevant.
GstCaps *caps; the GstCaps describing the data format in this buffer
guint64 offset; a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.
guint64 offset_end; the last offset contained in this buffer. It has the same format as offset.
guint8 *malloc_data; a pointer to the allocated memory associated with this buffer. When the buffer is freed, this data will freed with free().

enum GstBufferFlag

typedef enum {
  GST_BUFFER_FLAG_READONLY   = GST_MINI_OBJECT_FLAG_READONLY,
  GST_BUFFER_FLAG_PREROLL    = (GST_MINI_OBJECT_FLAG_LAST << 0),
  GST_BUFFER_FLAG_DISCONT    = (GST_MINI_OBJECT_FLAG_LAST << 1),
  GST_BUFFER_FLAG_IN_CAPS    = (GST_MINI_OBJECT_FLAG_LAST << 2),
  GST_BUFFER_FLAG_GAP        = (GST_MINI_OBJECT_FLAG_LAST << 3),
  GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 4),
  /* 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_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.
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)

A flags word containing GstBufferFlag flags set on this buffer.

buf : a GstBuffer.

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 specific flag on a buffer.

buf : a GstBuffer.
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 on a buffer.

buf : a GstBuffer.
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.
flag : the GstBufferFlag to clear.

GST_BUFFER_DATA()

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

A pointer to the data element of this buffer.

buf : a GstBuffer.

GST_BUFFER_MALLOCDATA()

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

A pointer to any data allocated for this buffer using malloc(). If this is non-NULL, this memory will be freed at the end of the buffer's lifecycle (i.e. when its refcount becomes zero).

buf : a GstBuffer.

GST_BUFFER_SIZE()

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

The size in bytes of the data in this buffer.

buf : a GstBuffer.

GST_BUFFER_TIMESTAMP()

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

The timestamp in nanoseconds (as a GstClockTime) of the data in the buffer. Value will be GST_CLOCK_TIME_NONE if the timestamp is unknown.

buf : a GstBuffer.:

GST_BUFFER_DURATION()

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

The duration in nanoseconds (as a GstClockTime) of the data in the buffer. Value will be GST_CLOCK_TIME_NONE if the duration is unknown.

buf : a GstBuffer.

GST_BUFFER_CAPS()

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

The caps for this buffer.

buf : a GstBuffer.

GST_BUFFER_OFFSET()

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

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

buf : a GstBuffer.

GST_BUFFER_OFFSET_END()

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

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

buf : a GstBuffer.

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 : a GstBuffer

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 : a GstBuffer

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 : a GstBuffer

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 : a GstBuffer

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.

MT safe.

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.

MT safe.

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

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.

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. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will also be freed at this time.

buf : a 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. This will replace any existing data pointer set on this buffer, but will not change GST_BUFFER_MALLOCDATA(), if any. Callers should ensure that GST_BUFFER_MALLOCDATA() is non-NULL, or should free that and set it to NULL.

No checks are done on the data or size arguments passed.

buf : a GstBuffer
data : The data (a guint8 *) to set on the buffer.
size : The size (in bytes, as a guint) of the data being set.

gst_buffer_copy()

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

Create a copy of the given buffer. This will also make a newly allocated copy of the data the source buffer contains.

buf : a GstBuffer.

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

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. If the source buffer is already writable, this will simply return the same buffer. A copy will otherwise be made using gst_buffer_copy().

buf : a GstBuffer

gst_buffer_replace()

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

Modifies a pointer to a Gstbuffer to point to a different GstBuffer. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer is unreffed, the new is reffed).

Either nbuf or the GstBuffer pointed to by obuf may be NULL.

obuf : pointer to a pointer to a GstBuffer to be replaced.
nbuf : pointer to a GstBuffer that will replace the buffer pointed to by obuf.

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 no media type attached to this buffer.

Returns: a reference to the GstCaps.

buffer : a GstBuffer.
Returns :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 refcount of the caps will be increased and any previous caps on the buffer will be unreffed.

buffer : a GstBuffer.
caps : a GstCaps.

gst_buffer_create_sub ()

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

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, else they are set to GST_CLOCK_TIME_NONE/GST_BUFFER_OFFSET_NONE. The duration field of the new buffer is set to GST_CLOCK_TIME_NONE.

MT safe. Returns: the new GstBuffer.

parent : a GstBuffer.
offset : the offset into parent GstBuffer at which the new sub-buffer begins.
size : the size of the new GstBuffer sub-buffer, in bytes (with size > 0).
Returns :NULL if the arguments were invalid.

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 sub-buffers of the same buffer.

MT safe.

buf1 : the first GstBuffer.
buf2 : the second 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.

MT safe. Returns: the new GstBuffer that spans the two source buffers.

buf1 : the 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 :NULL if the arguments are invalid.

gst_buffer_stamp ()

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

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.

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 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 GstBuffer.
buf2 : the second source GstBuffer.
Returns : the new GstBuffer which is 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 : the first source GstBuffer to merge.
buf2 : the second source GstBuffer to merge.
Returns : the new GstBuffer which is the concatenation of the source buffers.