gstadapter

gstadapter — object to splice and merge buffers to desired size

Synopsis


#include <gst/bytestream/adapter.h>


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

Description

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.

Details

GstAdapter

typedef struct {
  GObject	object;
} GstAdapter;


gst_adapter_new ()

GstAdapter* gst_adapter_new                 (void);

Creates a new GstAdapter.

Returns : a new GstAdapter

gst_adapter_clear ()

void        gst_adapter_clear               (GstAdapter *adapter);

Removes all buffers from the adapter.

adapter : the GstAdapter to clear

gst_adapter_push ()

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

gst_adapter_peek ()

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

gst_adapter_flush ()

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

gst_adapter_available ()

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

gst_adapter_available_fast ()

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

See Also

GstBytestream, GstFilePad