![]() |
![]() |
![]() |
GStreamer 0.10 Core Reference Manual | ![]() |
---|---|---|---|---|
#include <gst/gst.h> GstBufferList; GstBufferListIterator; GstBuffer* (*GstBufferListDoFunction) (GstBuffer *buffer, gpointer user_data); GstBufferList* gst_buffer_list_new (void); GstBufferList* gst_buffer_list_ref (GstBufferList *list); void gst_buffer_list_unref (GstBufferList *list); GstBufferList* gst_buffer_list_copy (const GstBufferList *list); #define gst_buffer_list_is_writable (list) #define gst_buffer_list_make_writable (list) guint gst_buffer_list_n_groups (GstBufferList *list); enum GstBufferListItem; GstBufferListItem (*GstBufferListFunc) (GstBuffer **buffer, guint group, guint idx, gpointer user_data); void gst_buffer_list_foreach (GstBufferList *list, GstBufferListFunc func, gpointer user_data); GstBuffer* gst_buffer_list_get (GstBufferList *list, guint group, guint idx); GstBufferListIterator* gst_buffer_list_iterate (GstBufferList *list); void gst_buffer_list_iterator_free (GstBufferListIterator *it); guint gst_buffer_list_iterator_n_buffers (const GstBufferListIterator *it); void gst_buffer_list_iterator_add (GstBufferListIterator *it, GstBuffer *buffer); void gst_buffer_list_iterator_add_group (GstBufferListIterator *it); GstBuffer* gst_buffer_list_iterator_next (GstBufferListIterator *it); gboolean gst_buffer_list_iterator_next_group (GstBufferListIterator *it); void gst_buffer_list_iterator_remove (GstBufferListIterator *it); GstBuffer* gst_buffer_list_iterator_steal (GstBufferListIterator *it); void gst_buffer_list_iterator_take (GstBufferListIterator *it, GstBuffer *buffer); GstBuffer* gst_buffer_list_iterator_do (GstBufferListIterator *it, GstBufferListDoFunction do_func, gpointer user_data); GstBuffer* gst_buffer_list_iterator_merge_group (const GstBufferListIterator *it);
Buffer lists are units of grouped scatter/gather data transfer in GStreamer.
Buffer lists are created with gst_buffer_list_new()
and filled with data
using a GstBufferListIterator. The iterator has no current buffer; its
cursor position lies between buffers, immediately before the buffer that
would be returned by gst_buffer_list_iterator_next()
. After iterating to the
end of a group the iterator must be advanced to the next group by a call to
gst_buffer_list_iterator_next_group()
before any further calls to
gst_buffer_list_iterator_next()
can return buffers again. The cursor position
of a newly created iterator lies before the first group; a call to
gst_buffer_list_iterator_next_group()
is necessary before calls to
gst_buffer_list_iterator_next()
can return buffers.
+--- group0 ----------------------+--- group1 ------------+ | buffer0 buffer1 buffer2 | buffer3 buffer4 | ^ ^ ^ ^ ^ ^ ^ ^ Iterator positions
The gst_buffer_list_iterator_remove()
, gst_buffer_list_iterator_steal()
,
gst_buffer_list_iterator_take()
and gst_buffer_list_iterator_do()
functions
are not defined in terms of the cursor position; they operate on the last
element returned from gst_buffer_list_iterator_next()
.
The basic use pattern of creating a buffer list with an iterator is as follows:
Example 4. Creating a buffer list
GstBufferList *list; GstBufferListIterator *it; list = gst_buffer_list_new (); it = gst_buffer_list_iterate (list); gst_buffer_list_iterator_add_group (it); gst_buffer_list_iterator_add (it, header1); gst_buffer_list_iterator_add (it, data1); gst_buffer_list_iterator_add_group (it); gst_buffer_list_iterator_add (it, header2); gst_buffer_list_iterator_add (it, data2); gst_buffer_list_iterator_add_group (it); gst_buffer_list_iterator_add (it, header3); gst_buffer_list_iterator_add (it, data3); ... gst_buffer_list_iterator_free (it);
The basic use pattern of iterating over a buffer list is as follows:
Example 5. Iterating a buffer list
GstBufferListIterator *it; it = gst_buffer_list_iterate (list); while (gst_buffer_list_iterator_next_group (it)) { while ((buffer = gst_buffer_list_iterator_next (it)) != NULL) { do_something_with_buffer (buffer); } } gst_buffer_list_iterator_free (it);
The basic use pattern of modifying a buffer in a list is as follows:
Example 6. Modifying the data of the first buffer in a list
GstBufferListIterator *it; list = gst_buffer_list_make_writable (list); it = gst_buffer_list_iterate (list); if (gst_buffer_list_iterator_next_group (it)) { GstBuffer *buf buf = gst_buffer_list_iterator_next (it); if (buf != NULL) { buf = gst_buffer_list_iterator_do (it, (GstBufferListDoFunction) gst_mini_object_make_writable, NULL); modify_data (GST_BUFFER_DATA (buf)); } } gst_buffer_list_iterator_free (it);
typedef struct _GstBufferListIterator GstBufferListIterator;
Opaque iterator for a GstBufferList.
GstBuffer* (*GstBufferListDoFunction) (GstBuffer *buffer, gpointer user_data);
A function for accessing the last buffer returned by
gst_buffer_list_iterator_next()
. The function can leave buffer
in the list,
replace buffer
in the list or remove buffer
from the list, depending on
the return value. If the function returns NULL, buffer
will be removed from
the list, otherwise buffer
will be replaced with the returned buffer.
The last buffer returned by gst_buffer_list_iterator_next()
will be replaced
with the buffer returned from the function. The function takes ownership of
buffer
and if a different value than buffer
is returned, buffer
must be
unreffed. If NULL is returned, the buffer will be removed from the list. The
list must be writable.
buffer : |
the GstBuffer |
user_data : |
user data |
Returns : | the buffer to replace buffer in the list, or NULL to remove buffer
from the list
|
GstBufferList* gst_buffer_list_new (void);
Creates a new, empty GstBufferList. The caller is responsible for unreffing the returned GstBufferList.
Returns : | the new GstBufferList. gst_buffer_list_unref() after usage.
|
GstBufferList* gst_buffer_list_ref (GstBufferList *list);
Increases the refcount of the given buffer list by one.
Note that the refcount affects the writeability of list
and its data, see
gst_buffer_list_make_writable()
. It is important to note that keeping
additional references to GstBufferList instances can potentially increase
the number of memcpy operations in a pipeline.
list : |
a GstBufferList |
Returns : | list
|
void gst_buffer_list_unref (GstBufferList *list);
Decreases the refcount of the buffer list. If the refcount reaches 0, the buffer list will be freed.
list : |
a GstBufferList |
GstBufferList* gst_buffer_list_copy (const GstBufferList *list);
Create a shallow copy of the given buffer list. This will make a newly allocated copy of the source list with copies of buffer pointers. The refcount of buffers pointed to will be increased by one.
list : |
a GstBufferList |
Returns : | a new copy of list .
|
#define gst_buffer_list_is_writable(list) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (list))
Tests if you can safely add buffers and groups into a buffer list.
list : |
a GstBufferList |
#define gst_buffer_list_make_writable(list) GST_BUFFER_LIST_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (list)))
Makes a writable buffer list from the given buffer list. If the source buffer
list is already writable, this will simply return the same buffer list. A
copy will otherwise be made using gst_buffer_list_copy()
.
list : |
a GstBufferList |
guint gst_buffer_list_n_groups (GstBufferList *list);
Returns the number of groups in list
.
list : |
a GstBufferList |
Returns : | the number of groups in the buffer list |
typedef enum { GST_BUFFER_LIST_CONTINUE, GST_BUFFER_LIST_SKIP_GROUP, GST_BUFFER_LIST_END } GstBufferListItem;
The result of the GstBufferListFunc.
GstBufferListItem (*GstBufferListFunc) (GstBuffer **buffer, guint group, guint idx, gpointer user_data);
A function that will be called from gst_buffer_list_foreach()
. The buffer
field will point to a the reference of the buffer at idx
in group
.
When this function returns GST_BUFFER_LIST_CONTINUE, the next buffer will be
returned. When GST_BUFFER_LIST_SKIP_GROUP is returned, all remaining buffers
in the current group will be skipped and the first buffer of the next group
is returned (if any). When GST_BUFFER_LIST_END is returned,
gst_buffer_list_foreach()
will return.
When buffer
is set to NULL, the item will be removed from the bufferlist.
When buffer
has been made writable, the new buffer reference can be assigned
to buffer
. This function is responsible for unreffing the old buffer when
removing or modifying.
buffer : |
pointer the buffer |
group : |
the group index of buffer
|
idx : |
the index in group of buffer
|
user_data : |
user data passed to gst_buffer_list_foreach()
|
Returns : | a GstBufferListItem |
void gst_buffer_list_foreach (GstBufferList *list, GstBufferListFunc func, gpointer user_data);
Call func
with data
for each buffer in list
.
func
can modify the passed buffer pointer or its contents. The return value
of func
define if this function returns or if the remaining buffers in a
group should be skipped.
list : |
a GstBufferList |
func : |
a GstBufferListFunc to call |
user_data : |
user data passed to func
|
GstBuffer* gst_buffer_list_get (GstBufferList *list, guint group, guint idx);
Get the buffer at idx
in group
.
Note that this function is not efficient for iterating over the entire list.
Use an iterator or gst_buffer_list_foreach()
instead.
list : |
a GstBufferList |
group : |
the group |
idx : |
the index in group
|
Returns : | the buffer at idx in group or NULL when there is no buffer. The
buffer remains valid as long as list is valid.
|
GstBufferListIterator* gst_buffer_list_iterate (GstBufferList *list);
Iterate the buffers in list
. The owner of the iterator must also be the
owner of a reference to list
while the returned iterator is in use.
list : |
a GstBufferList |
Returns : | a new GstBufferListIterator of the buffers in list .
gst_buffer_list_iterator_free() after usage
|
void gst_buffer_list_iterator_free (GstBufferListIterator *it);
Free the iterator.
it : |
the GstBufferListIterator to free |
guint gst_buffer_list_iterator_n_buffers (const GstBufferListIterator *it);
Returns the number of buffers left to iterate in the current group. I.e. the
number of calls that can be made to gst_buffer_list_iterator_next()
before
it returns NULL.
This function will not move the implicit cursor or in any other way affect
the state of the iterator it
.
it : |
a GstBufferListIterator |
Returns : | the number of buffers left to iterate in the current group |
void gst_buffer_list_iterator_add (GstBufferListIterator *it, GstBuffer *buffer);
Inserts buffer
into the GstBufferList iterated with it
. The buffer is
inserted into the current group, immediately before the buffer that would be
returned by gst_buffer_list_iterator_next()
. The buffer is inserted before
the implicit cursor, a subsequent call to gst_buffer_list_iterator_next()
will return the buffer after the inserted buffer, if any.
This function takes ownership of buffer
.
it : |
a GstBufferListIterator |
buffer : |
a GstBuffer |
void gst_buffer_list_iterator_add_group (GstBufferListIterator *it);
Inserts a new, empty group into the GstBufferList iterated with it
. The
group is inserted immediately before the group that would be returned by
gst_buffer_list_iterator_next_group()
. A subsequent call to
gst_buffer_list_iterator_next_group()
will advance the iterator to the group
after the inserted group, if any.
it : |
a GstBufferListIterator |
GstBuffer* gst_buffer_list_iterator_next (GstBufferListIterator *it);
Returns the next buffer in the list iterated with it
. If the iterator is at
the end of a group, NULL will be returned. This function may be called
repeatedly to iterate through the current group.
The caller will not get a new ref to the returned GstBuffer and must not unref it.
it : |
a GstBufferListIterator |
Returns : | the next buffer in the current group of the buffer list, or NULL |
gboolean gst_buffer_list_iterator_next_group (GstBufferListIterator *it);
Advance the iterator it
to the first buffer in the next group. If the
iterator is at the last group, FALSE will be returned. This function may be
called repeatedly to iterate through the groups in a buffer list.
it : |
a GstBufferListIterator |
Returns : | TRUE if the iterator could be advanced to the next group, FALSE if the iterator was already at the last group |
void gst_buffer_list_iterator_remove (GstBufferListIterator *it);
Removes the last buffer returned by gst_buffer_list_iterator_next()
from
the GstBufferList iterated with it
. gst_buffer_list_iterator_next()
must
have been called on it
before this function is called. This function can
only be called once per call to gst_buffer_list_iterator_next()
.
The removed buffer is unreffed.
it : |
a GstBufferListIterator |
GstBuffer* gst_buffer_list_iterator_steal (GstBufferListIterator *it);
Returns the last buffer returned by gst_buffer_list_iterator_next()
without
modifying the refcount of the buffer.
it : |
a GstBufferListIterator |
Returns : | the last buffer returned by gst_buffer_list_iterator_next()
|
void gst_buffer_list_iterator_take (GstBufferListIterator *it, GstBuffer *buffer);
Replaces the last buffer returned by gst_buffer_list_iterator_next()
with
buffer
in the GstBufferList iterated with it
and takes ownership of
buffer
. gst_buffer_list_iterator_next()
must have been called on it
before
this function is called. gst_buffer_list_iterator_remove()
must not have been
called since the last call to gst_buffer_list_iterator_next()
.
This function unrefs the replaced buffer if it has not been stolen with
gst_buffer_list_iterator_steal()
and takes ownership of buffer
(i.e. the
refcount of buffer
is not increased).
it : |
a GstBufferListIterator |
buffer : |
a GstBuffer |
GstBuffer* gst_buffer_list_iterator_do (GstBufferListIterator *it, GstBufferListDoFunction do_func, gpointer user_data);
Calls the given function for the last buffer returned by
gst_buffer_list_iterator_next()
. gst_buffer_list_iterator_next()
must have
been called on it
before this function is called.
gst_buffer_list_iterator_remove()
and gst_buffer_list_iterator_steal()
must
not have been called since the last call to gst_buffer_list_iterator_next()
.
See GstBufferListDoFunction for more details.
it : |
a GstBufferListIterator |
do_func : |
the function to be called |
user_data : |
the gpointer to optional user data. |
Returns : | the return value from do_func
|
GstBuffer* gst_buffer_list_iterator_merge_group (const GstBufferListIterator *it);
Merge a buffer list group into a normal GstBuffer by copying its metadata
and memcpying its data into consecutive memory. All buffers in the current
group after the implicit cursor will be merged into one new buffer. The
metadata of the new buffer will be a copy of the metadata of the buffer that
would be returned by gst_buffer_list_iterator_next()
. If there is no buffer
in the current group after the implicit cursor, NULL will be returned.
This function will not move the implicit cursor or in any other way affect
the state of the iterator it
or the list.
it : |
a GstBufferListIterator |
Returns : | a new GstBuffer, gst_buffer_unref() after usage, or NULL
|