![]() | ![]() | ![]() | GStreamer 0.8 Core API Reference (0.8.0) | ![]() |
---|
GstBuffer — Data-passing buffer type, supporting sub-buffers.
#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);
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)
#define GST_BUFFER_TRACE_NAME "GstBuffer"
The name used for tracing memory allocations
#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. |
#define GST_IS_BUFFER(buf) (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)
Checks if the pointer is a GstBuffer.
buf : | a pointer to query. |
#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. |
#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. |
#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. |
#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. |
#define GST_BUFFER_FLAGS(buf) GST_DATA_FLAGS(buf)
Gets the flags from this buffer.
buf : | a GstBuffer to retrieve the flags from. |
#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. |
#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. |
#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. |
#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. |
#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. |
#define GST_BUFFER_MAXSIZE(buf) (GST_BUFFER(buf)->maxsize)
Gets the maximum size of this buffer.
buf : | a GstBuffer to get maximum size of. |
#define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER(buf)->timestamp)
Gets the timestamp for this buffer.
buf : | a GstBuffer to get timestamp of. |
#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. |
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_READONLY | the buffer is read-only. |
GST_BUFFER_SUBBUFFER | the buffer is a subbuffer, the parent buffer can be found with the GST_BUFFER_POOL_PRIVATE() macro. |
GST_BUFFER_ORIGINAL | buffer is not a copy of another buffer. |
GST_BUFFER_DONTFREE | do not try to free the data when this buffer is unreferenced. |
GST_BUFFER_KEY_UNIT | the buffer holds a key unit, a unit that can be decoded independently of other buffers. |
GST_BUFFER_DONTKEEP | |
GST_BUFFER_FLAG_LAST | additional flags can be added starting from this flag. |
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.
GstBuffer* gst_buffer_new (void);
Creates a newly allocated buffer without any data.
Returns : | the new GstBuffer. |
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. |
#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 |
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. |
GstBuffer* gst_buffer_default_copy (GstBuffer *buffer);
Make a full newly allocated copy of the given buffer, data and all.
#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. |
#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. |
#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. |
#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.
#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.
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.
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.
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.
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.
<< GstBin | GstConfig >> |