![]() | ![]() | ![]() | GStreamer 0.8 Core API Reference (0.8.4) | ![]() |
---|
GstBuffer — Data-passing buffer type, supporting sub-buffers.
struct GstBuffer; void (*GstBufferFreeDataFunc) (GstBuffer *buffer); #define GST_BUFFER_TRACE_NAME #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_DURATION (buf) #define GST_BUFFER_OFFSET (buf) #define GST_BUFFER_OFFSET_END (buf) #define GST_BUFFER_FREE_DATA_FUNC (buf) #define GST_BUFFER_PRIVATE (buf) #define GST_BUFFER_OFFSET_NONE #define GST_BUFFER_MAXSIZE_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_MAXSIZE_IS_VALID (buffer) enum GstBufferFlag; GstBuffer* gst_buffer_new (void); GstBuffer* gst_buffer_new_and_alloc (guint size); #define gst_buffer_set_data (buf, data, size) #define gst_buffer_ref (buf) #define gst_buffer_ref_by_count (buf,c) #define gst_buffer_unref (buf) void gst_buffer_stamp (GstBuffer *dest, const GstBuffer *src); #define gst_buffer_copy (buf) #define gst_buffer_is_writable (buf) #define gst_buffer_copy_on_write (buf) GstBuffer* gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size); GstBuffer* gst_buffer_join (GstBuffer *buf1, GstBuffer *buf2); 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); void gst_buffer_default_free (GstBuffer *buffer); GstBuffer* gst_buffer_default_copy (GstBuffer *buffer);
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_DATA (buffer) = g_alloc (size); ...
Alternatively, use gst_buffer_new_and_alloc() to create a buffer with preallocated data of a given size.
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)
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.
#define GST_BUFFER_TRACE_NAME "GstBuffer"
The name used for tracing memory allocations
#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. |
#define GST_BUFFER_FREE_DATA_FUNC(buf) (GST_BUFFER(buf)->free_data)
buf : |
#define GST_BUFFER_DURATION_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
buffer : |
#define GST_BUFFER_TIMESTAMP_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))
buffer : |
#define GST_BUFFER_OFFSET_IS_VALID(buffer) (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)
buffer : |
#define GST_BUFFER_OFFSET_END_IS_VALID(buffer) (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)
buffer : |
#define GST_BUFFER_MAXSIZE_IS_VALID(buffer) (GST_BUFFER_MAXSIZE (buffer) != GST_BUFFER_MAXSIZE_NONE)
buffer : |
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, /* sync point in the stream */ GST_BUFFER_DONTKEEP, GST_BUFFER_IN_CAPS, 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_IN_CAPS | the buffer has been added as a field in a GstCaps. |
GST_BUFFER_FLAG_LAST | additional flags can be added starting from this flag. |
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 |
#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. |
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 |
#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_is_writable(buf) gst_data_is_writable (GST_DATA (buf))
buf : |
#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_join (GstBuffer *buf1, GstBuffer *buf2);
Create a new buffer that is the concatenation of the two source buffers. The original buffers are unreferenced.
If the buffers point to contiguous areas of memory, the buffer is created without copying the data.
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.
WARNING: Incorrect use of this function can lead to memory leaks. It is recommended to use gst_buffer_join() instead of this function.
If the buffers point to contiguous areas of memory, the buffer is created without copying the data.
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.
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.
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. |
<< GstBin | GstConfig >> |