| GStreamer 0.9 Core Reference Manual |
|---|
GstAdapterGstAdapter — object to splice and merge buffers to desired size |
#include <gst/base/gstadapter.h>
GstAdapter;
GstAdapterClass;
GstAdapter* gst_adapter_new (void);
void gst_adapter_clear (GstAdapter *adapter);
void gst_adapter_push (GstAdapter *adapter,
GstBuffer *buf);
const guint8* gst_adapter_peek (GstAdapter *adapter,
guint size);
void gst_adapter_flush (GstAdapter *adapter,
guint flush);
guint gst_adapter_available (GstAdapter *adapter);
guint gst_adapter_available_fast (GstAdapter *adapter);
guint8* gst_adapter_take (GstAdapter *adapter,
guint nbytes);
This class is for elements that receive buffers in an undesired size. While for example raw video contains one image per buffer, the same is not true for a lot of other formats, especially those that come directly from a file. So if you have undefined buffer sizes and require a specific size, this object is for you.
The theory of operation is like this: All buffers received are put
into the adapter using gst_adapter_push() and the data is then read back
in chunks of the desired size using gst_adapter_peek(). After the data is
processed, it is freed using gst_adapter_flush(). An example function that
needs to process data in 10 byte chunks could look like this:
void
process_buffer (GstAdapter *adapter, GstBuffer *buffer)
{
guint8 *data;
// put buffer into adapter
gst_adapter_push (adapter, buffer);
// while we can read out 10 bytes, process them
while ((data = gst_adapter_peek (adapter, 10))) {
// process the 10 bytes here
// after processing the data, flush it
gst_adapter_flush (adapter, 10);
}
}
For another example, a simple element inside GStreamer that uses GstAdapter is the libvisual element.
A last thing to note is that while GstAdapter is pretty optimized,
merging buffers still might be an operation that requires a memcpy()
operation, and this operation is not the fastest. Because of this, some
functions like gst_adapter_available_fast() are provided to help speed up
such cases should you want to.
GstAdapter* gst_adapter_new (void);
Creates a new GstAdapter.
| Returns : | a new GstAdapter |
void gst_adapter_clear (GstAdapter *adapter);
Removes all buffers from the adapter.
adapter : |
the GstAdapter to clear |
void gst_adapter_push (GstAdapter *adapter, GstBuffer *buf);
Adds the data from buf to the data stored inside adapter and takes
ownership of the buffer.
adapter : |
a GstAdapter |
buf : |
the GstBuffer to queue into the adapter |
const guint8* gst_adapter_peek (GstAdapter *adapter, guint size);
Gets the first size bytes stored in the adapter. If this many bytes are
not available, it returns NULL. The returned pointer is valid until the next
function is called on the adapter.
adapter : |
a GstAdapter |
size : |
number of bytes to peek |
| Returns : | a pointer to the first size bytes of data or NULL
|
void gst_adapter_flush (GstAdapter *adapter, guint flush);
Flushes the first flush bytes of the adapter.
adapter : |
a GstAdapter |
flush : |
number of bytes to flush |
guint gst_adapter_available (GstAdapter *adapter);
Gets the maximum amount of bytes available, that is it returns the maximum
value that can be supplied to gst_adapter_peek() without that function
returning NULL.
adapter : |
a GstAdapter |
| Returns : | amount of bytes available in adapter
|
guint gst_adapter_available_fast (GstAdapter *adapter);
Gets the maximum amount of bytes available without the need to do expensive operations (like copying the data into a temporary buffer).
adapter : |
a GstAdapter |
| Returns : | amount of bytes available in adapter without expensive operations
|
guint8* gst_adapter_take (GstAdapter *adapter, guint nbytes);
Returns a freshly allocated buffer containing the first nbytes bytes of the
adapter. g_free() the return value after use.
adapter : |
a GstAdapter |
nbytes : |
number of bytes to take |
| Returns : | oven-fresh hot data, or NULL if nbytes bytes are not available
|
| << GStreamer Base Classes | GstBaseSrc >> |