gst/gstbufferlist.c

   1 /* GStreamer
   2  * Copyright (C) 2009 Axis Communications <dev-gstreamer at axis dot com>
   3  * @author Jonas Holmberg <jonas dot holmberg at axis dot com>
   4  *
   5  * gstbufferlist.c: Buffer list
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstbufferlist
  25  * @short_description: Lists of buffers for data-passing
  26  * @see_also: #GstPad, #GstMiniObject
  27  *
  28  * Buffer lists are an object containing a list of buffers.
  29  *
  30  * Buffer lists are created with gst_buffer_list_new() and filled with data
  31  * using a gst_buffer_list_insert().
  32  *
  33  * Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is
  34  * interesting when multiple buffers need to be pushed in one go because it
  35  * can reduce the amount of overhead for pushing each buffer individually.
  36  *
  37  * Last reviewed on 2012-03-28 (0.11.3)
  38  */
  39 #include "gst_private.h"
  40
  41 #include "gstbuffer.h"
  42 #include "gstbufferlist.h"
  43
  44 #define GST_CAT_DEFAULT GST_CAT_BUFFER_LIST
  45
  46 /**
  47  * GstBufferList:
  48  *
  49  * Opaque list of grouped buffers.
  50  *
  51  * Since: 0.10.24
  52  */
  53 struct _GstBufferList
  54 {
  55   GstMiniObject mini_object;
  56
  57   GArray *array;
  58 };
  59
  60 GType _gst_buffer_list_type = 0;
  61
  62 GST_DEFINE_MINI_OBJECT_TYPE (GstBufferList, gst_buffer_list);
  63
  64 void
  65 _priv_gst_buffer_list_initialize (void)
  66 {
  67   _gst_buffer_list_type = gst_buffer_list_get_type ();
  68 }
  69
  70 static GstBufferList *
  71 _gst_buffer_list_copy (GstBufferList * list)
  72 {
  73   GstBufferList *copy;
  74   guint i, len;
  75
  76   len = list->array->len;
  77   copy = gst_buffer_list_new_sized (len);
  78
  79   /* add and ref all buffers in the array */
  80   for (i = 0; i < len; i++) {
  81     GstBuffer *buf = g_array_index (list->array, GstBuffer *, i);
  82     buf = gst_buffer_ref (buf);
  83     g_array_append_val (copy->array, buf);
  84   }
  85   return copy;
  86 }
  87
  88 static void
  89 _gst_buffer_list_free (GstBufferList * list)
  90 {
  91   guint i, len;
  92   GST_LOG ("free %p", list);
  93
  94   /* unrefs all buffers too */
  95   len = list->array->len;
  96   for (i = 0; i < len; i++)
  97     gst_buffer_unref (g_array_index (list->array, GstBuffer *, i));
  98   g_array_free (list->array, TRUE);
  99
 100   g_slice_free1 (sizeof (GstBufferList), list);
 101 }
 102
 103 static void
 104 gst_buffer_list_init (GstBufferList * list, guint asize)
 105 {
 106   gst_mini_object_init (GST_MINI_OBJECT_CAST (list), _gst_buffer_list_type,
 107       (GstMiniObjectCopyFunction) _gst_buffer_list_copy, NULL,
 108       (GstMiniObjectFreeFunction) _gst_buffer_list_free);
 109
 110   list->array = g_array_sized_new (FALSE, FALSE, sizeof (GstBuffer *), asize);
 111
 112   GST_LOG ("init %p", list);
 113 }
 114
 115 /**
 116  * gst_buffer_list_new_sized:
 117  * @size: an initial reserved size
 118  *
 119  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 120  * the returned #GstBufferList. The list will have @size space preallocated so
 121  * that memory reallocations can be avoided.
 122  *
 123  * Free-function: gst_buffer_list_unref
 124  *
 125  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 126  *     after usage.
 127  *
 128  * Since: 0.10.24
 129  */
 130 GstBufferList *
 131 gst_buffer_list_new_sized (guint size)
 132 {
 133   GstBufferList *list;
 134
 135   list = g_slice_new0 (GstBufferList);
 136
 137   GST_LOG ("new %p", list);
 138
 139   gst_buffer_list_init (list, size);
 140
 141   return list;
 142 }
 143
 144 /**
 145  * gst_buffer_list_new:
 146  *
 147  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 148  * the returned #GstBufferList.
 149  *
 150  * Free-function: gst_buffer_list_unref
 151  *
 152  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 153  *     after usage.
 154  *
 155  * Since: 0.10.24
 156  */
 157 GstBufferList *
 158 gst_buffer_list_new (void)
 159 {
 160   return gst_buffer_list_new_sized (8);
 161 }
 162
 163 /**
 164  * gst_buffer_list_length:
 165  * @list: a #GstBufferList
 166  *
 167  * Returns the number of buffers in @list.
 168  *
 169  * Returns: the number of buffers in the buffer list
 170  *
 171  * Since: 0.10.24
 172  */
 173 guint
 174 gst_buffer_list_length (GstBufferList * list)
 175 {
 176   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 177
 178   return list->array->len;
 179 }
 180
 181 /**
 182  * gst_buffer_list_foreach:
 183  * @list: a #GstBufferList
 184  * @func: (scope call): a #GstBufferListFunc to call
 185  * @user_data: (closure): user data passed to @func
 186  *
 187  * Call @func with @data for each buffer in @list.
 188  *
 189  * @func can modify the passed buffer pointer or its contents. The return value
 190  * of @func define if this function returns or if the remaining buffers in
 191  * the list should be skipped.
 192  *
 193  * Since: 0.10.24
 194  */
 195 void
 196 gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
 197     gpointer user_data)
 198 {
 199   guint i, len;
 200
 201   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 202   g_return_if_fail (func != NULL);
 203
 204   len = list->array->len;
 205   for (i = 0; i < len;) {
 206     GstBuffer *buf, *buf_ret;
 207     gboolean ret;
 208
 209     buf = buf_ret = g_array_index (list->array, GstBuffer *, i);
 210     ret = func (&buf_ret, i, user_data);
 211
 212     /* Check if the function changed the buffer */
 213     if (buf != buf_ret) {
 214       if (buf_ret == NULL) {
 215         g_array_remove_index (list->array, i);
 216         len--;
 217       } else {
 218         g_array_index (list->array, GstBuffer *, i) = buf_ret;
 219       }
 220     }
 221
 222     if (!ret)
 223       break;
 224
 225     /* If the buffer was not removed by func go to the next buffer */
 226     if (buf_ret != NULL)
 227       i++;
 228   }
 229 }
 230
 231 /**
 232  * gst_buffer_list_get:
 233  * @list: a #GstBufferList
 234  * @idx: the index
 235  *
 236  * Get the buffer at @idx.
 237  *
 238  * Returns: (transfer none): the buffer at @idx in @group or NULL when there
 239  *     is no buffer. The buffer remains valid as long as @list is valid.
 240  *
 241  * Since: 0.10.24
 242  */
 243 GstBuffer *
 244 gst_buffer_list_get (GstBufferList * list, guint idx)
 245 {
 246   GstBuffer *buf;
 247
 248   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 249   g_return_val_if_fail (idx < list->array->len, NULL);
 250
 251   buf = g_array_index (list->array, GstBuffer *, idx);
 252
 253   return buf;
 254 }
 255
 256 /**
 257  * gst_buffer_list_add:
 258  * @l: a #GstBufferList
 259  * @b: a #GstBuffer
 260  *
 261  * Append @b at the end of @l.
 262  */
 263 /**
 264  * gst_buffer_list_insert:
 265  * @list: a #GstBufferList
 266  * @idx: the index
 267  * @buffer: a #GstBuffer
 268  *
 269  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 270  * this new buffer.
 271  *
 272  * A -1 value for @idx will append the buffer at the end.
 273  */
 274 void
 275 gst_buffer_list_insert (GstBufferList * list, guint idx, GstBuffer * buffer)
 276 {
 277   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 278   g_return_if_fail (buffer != NULL);
 279
 280   if (idx == -1)
 281     g_array_append_val (list->array, buffer);
 282   else {
 283     g_return_if_fail (idx < list->array->len);
 284     g_array_insert_val (list->array, idx, buffer);
 285   }
 286 }
 287
 288 /**
 289  * gst_buffer_list_remove:
 290  * @list: a #GstBufferList
 291  * @idx: the index
 292  * @length: the amount to remove
 293  *
 294  * Remove @length buffers starting from @idx in @list. The following buffers are
 295  * moved to close the gap.
 296  */
 297 void
 298 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 299 {
 300   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 301   g_return_if_fail (idx < list->array->len);
 302
 303   g_array_remove_range (list->array, idx, length);
 304 }