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
 108   list->mini_object.copy = (GstMiniObjectCopyFunction) _gst_buffer_list_copy;
 109   list->mini_object.free = (GstMiniObjectFreeFunction) _gst_buffer_list_free;
 110
 111   list->array = g_array_sized_new (FALSE, FALSE, sizeof (GstBuffer *), asize);
 112
 113   GST_LOG ("init %p", list);
 114 }
 115
 116 /**
 117  * gst_buffer_list_new_sized:
 118  * @size: an initial reserved size
 119  *
 120  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 121  * the returned #GstBufferList. The list will have @size space preallocated so
 122  * that memory reallocations can be avoided.
 123  *
 124  * Free-function: gst_buffer_list_unref
 125  *
 126  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 127  *     after usage.
 128  *
 129  * Since: 0.10.24
 130  */
 131 GstBufferList *
 132 gst_buffer_list_new_sized (guint size)
 133 {
 134   GstBufferList *list;
 135
 136   list = g_slice_new0 (GstBufferList);
 137
 138   GST_LOG ("new %p", list);
 139
 140   gst_buffer_list_init (list, size);
 141
 142   return list;
 143 }
 144
 145 /**
 146  * gst_buffer_list_new:
 147  *
 148  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 149  * the returned #GstBufferList.
 150  *
 151  * Free-function: gst_buffer_list_unref
 152  *
 153  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 154  *     after usage.
 155  *
 156  * Since: 0.10.24
 157  */
 158 GstBufferList *
 159 gst_buffer_list_new (void)
 160 {
 161   return gst_buffer_list_new_sized (8);
 162 }
 163
 164 /**
 165  * gst_buffer_list_length:
 166  * @list: a #GstBufferList
 167  *
 168  * Returns the number of buffers in @list.
 169  *
 170  * Returns: the number of buffers in the buffer list
 171  *
 172  * Since: 0.10.24
 173  */
 174 guint
 175 gst_buffer_list_length (GstBufferList * list)
 176 {
 177   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 178
 179   return list->array->len;
 180 }
 181
 182 /**
 183  * gst_buffer_list_foreach:
 184  * @list: a #GstBufferList
 185  * @func: (scope call): a #GstBufferListFunc to call
 186  * @user_data: (closure): user data passed to @func
 187  *
 188  * Call @func with @data for each buffer in @list.
 189  *
 190  * @func can modify the passed buffer pointer or its contents. The return value
 191  * of @func define if this function returns or if the remaining buffers in
 192  * the list should be skipped.
 193  *
 194  * Since: 0.10.24
 195  */
 196 void
 197 gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
 198     gpointer user_data)
 199 {
 200   guint i, len;
 201
 202   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 203   g_return_if_fail (func != NULL);
 204
 205   len = list->array->len;
 206   for (i = 0; i < len;) {
 207     GstBuffer *buf, *buf_ret;
 208     gboolean ret;
 209
 210     buf = buf_ret = g_array_index (list->array, GstBuffer *, i);
 211     ret = func (&buf_ret, i, user_data);
 212
 213     /* Check if the function changed the buffer */
 214     if (buf != buf_ret) {
 215       if (buf_ret == NULL) {
 216         g_array_remove_index (list->array, i);
 217         len--;
 218       } else {
 219         g_array_index (list->array, GstBuffer *, i) = buf_ret;
 220       }
 221     }
 222
 223     if (!ret)
 224       break;
 225
 226     /* If the buffer was not removed by func go to the next buffer */
 227     if (buf_ret != NULL)
 228       i++;
 229   }
 230 }
 231
 232 /**
 233  * gst_buffer_list_get:
 234  * @list: a #GstBufferList
 235  * @idx: the index
 236  *
 237  * Get the buffer at @idx.
 238  *
 239  * Returns: (transfer none): the buffer at @idx in @group or NULL when there
 240  *     is no buffer. The buffer remains valid as long as @list is valid.
 241  *
 242  * Since: 0.10.24
 243  */
 244 GstBuffer *
 245 gst_buffer_list_get (GstBufferList * list, guint idx)
 246 {
 247   GstBuffer *buf;
 248
 249   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 250   g_return_val_if_fail (idx < list->array->len, NULL);
 251
 252   buf = g_array_index (list->array, GstBuffer *, idx);
 253
 254   return buf;
 255 }
 256
 257 /**
 258  * gst_buffer_list_add:
 259  * @l: a #GstBufferList
 260  * @b: a #GstBuffer
 261  *
 262  * Append @b at the end of @l.
 263  */
 264 /**
 265  * gst_buffer_list_insert:
 266  * @list: a #GstBufferList
 267  * @idx: the index
 268  * @buffer: a #GstBuffer
 269  *
 270  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 271  * this new buffer.
 272  *
 273  * A -1 value for @idx will append the buffer at the end.
 274  */
 275 void
 276 gst_buffer_list_insert (GstBufferList * list, guint idx, GstBuffer * buffer)
 277 {
 278   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 279   g_return_if_fail (buffer != NULL);
 280
 281   if (idx == -1)
 282     g_array_append_val (list->array, buffer);
 283   else {
 284     g_return_if_fail (idx < list->array->len);
 285     g_array_insert_val (list->array, idx, buffer);
 286   }
 287 }
 288
 289 /**
 290  * gst_buffer_list_remove:
 291  * @list: a #GstBufferList
 292  * @idx: the index
 293  * @length: the amount to remove
 294  *
 295  * Remove @length buffers starting from @idx in @list. The following buffers are
 296  * moved to close the gap.
 297  */
 298 void
 299 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 300 {
 301   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 302   g_return_if_fail (idx < list->array->len);
 303
 304   g_array_remove_range (list->array, idx, length);
 305 }