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  * Copyright (C) 2014 Tim-Philipp Müller <tim at centricular dot com>
   5  *
   6  * gstbufferlist.c: Buffer list
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21  * Boston, MA 02110-1301, USA.
  22  */
  23
  24 /**
  25  * SECTION:gstbufferlist
  26  * @short_description: Lists of buffers for data-passing
  27  * @see_also: #GstPad, #GstMiniObject
  28  *
  29  * Buffer lists are an object containing a list of buffers.
  30  *
  31  * Buffer lists are created with gst_buffer_list_new() and filled with data
  32  * using a gst_buffer_list_insert().
  33  *
  34  * Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is
  35  * interesting when multiple buffers need to be pushed in one go because it
  36  * can reduce the amount of overhead for pushing each buffer individually.
  37  */
  38 #include "gst_private.h"
  39
  40 #include "gstbuffer.h"
  41 #include "gstbufferlist.h"
  42 #include "gstutils.h"
  43
  44 #define GST_CAT_DEFAULT GST_CAT_BUFFER_LIST
  45
  46 #define GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY(list) \
  47     ((list)->buffers != &(list)->arr[0])
  48
  49 /**
  50  * GstBufferList:
  51  *
  52  * Opaque list of grouped buffers.
  53  */
  54 struct _GstBufferList
  55 {
  56   GstMiniObject mini_object;
  57
  58   GstBuffer **buffers;
  59   guint n_buffers;
  60   guint n_allocated;
  61
  62   gsize slice_size;
  63
  64   /* one-item array, in reality more items are pre-allocated
  65    * as part of the GstBufferList structure, and that
  66    * pre-allocated array extends beyond the declared struct */
  67   GstBuffer *arr[1];
  68 };
  69
  70 GType _gst_buffer_list_type = 0;
  71
  72 GST_DEFINE_MINI_OBJECT_TYPE (GstBufferList, gst_buffer_list);
  73
  74 void
  75 _priv_gst_buffer_list_initialize (void)
  76 {
  77   _gst_buffer_list_type = gst_buffer_list_get_type ();
  78 }
  79
  80 static GstBufferList *
  81 _gst_buffer_list_copy (GstBufferList * list)
  82 {
  83   GstBufferList *copy;
  84   guint i, len;
  85
  86   len = list->n_buffers;
  87   copy = gst_buffer_list_new_sized (list->n_allocated);
  88
  89   /* add and ref all buffers in the array */
  90   for (i = 0; i < len; i++)
  91     copy->buffers[i] = gst_buffer_ref (list->buffers[i]);
  92
  93   copy->n_buffers = len;
  94
  95   return copy;
  96 }
  97
  98 static void
  99 _gst_buffer_list_free (GstBufferList * list)
 100 {
 101   guint i, len;
 102
 103   GST_LOG ("free %p", list);
 104
 105   /* unrefs all buffers too */
 106   len = list->n_buffers;
 107   for (i = 0; i < len; i++)
 108     gst_buffer_unref (list->buffers[i]);
 109
 110   if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list))
 111     g_free (list->buffers);
 112
 113   g_slice_free1 (list->slice_size, list);
 114 }
 115
 116 static void
 117 gst_buffer_list_init (GstBufferList * list, guint n_allocated, gsize slice_size)
 118 {
 119   gst_mini_object_init (GST_MINI_OBJECT_CAST (list), 0, _gst_buffer_list_type,
 120       (GstMiniObjectCopyFunction) _gst_buffer_list_copy, NULL,
 121       (GstMiniObjectFreeFunction) _gst_buffer_list_free);
 122
 123   list->buffers = &list->arr[0];
 124   list->n_buffers = 0;
 125   list->n_allocated = n_allocated;
 126   list->slice_size = slice_size;
 127
 128   GST_LOG ("init %p", list);
 129 }
 130
 131 /**
 132  * gst_buffer_list_new_sized:
 133  * @size: an initial reserved size
 134  *
 135  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 136  * the returned #GstBufferList. The list will have @size space preallocated so
 137  * that memory reallocations can be avoided.
 138  *
 139  * Free-function: gst_buffer_list_unref
 140  *
 141  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 142  *     after usage.
 143  */
 144 GstBufferList *
 145 gst_buffer_list_new_sized (guint size)
 146 {
 147   GstBufferList *list;
 148   gsize slice_size;
 149   guint n_allocated;
 150
 151   n_allocated = GST_ROUND_UP_16 (size);
 152
 153   slice_size = sizeof (GstBufferList) + (n_allocated - 1) * sizeof (gpointer);
 154
 155   list = g_slice_alloc0 (slice_size);
 156
 157   GST_LOG ("new %p", list);
 158
 159   gst_buffer_list_init (list, n_allocated, slice_size);
 160
 161   return list;
 162 }
 163
 164 /**
 165  * gst_buffer_list_new:
 166  *
 167  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 168  * the returned #GstBufferList.
 169  *
 170  * Free-function: gst_buffer_list_unref
 171  *
 172  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 173  *     after usage.
 174  */
 175 GstBufferList *
 176 gst_buffer_list_new (void)
 177 {
 178   return gst_buffer_list_new_sized (8);
 179 }
 180
 181 /**
 182  * gst_buffer_list_length:
 183  * @list: a #GstBufferList
 184  *
 185  * Returns the number of buffers in @list.
 186  *
 187  * Returns: the number of buffers in the buffer list
 188  */
 189 guint
 190 gst_buffer_list_length (GstBufferList * list)
 191 {
 192   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 193
 194   return list->n_buffers;
 195 }
 196
 197 static inline void
 198 gst_buffer_list_remove_range_internal (GstBufferList * list, guint idx,
 199     guint length, gboolean unref_old)
 200 {
 201   guint i;
 202
 203   if (unref_old) {
 204     for (i = idx; i < idx + length; ++i)
 205       gst_buffer_unref (list->buffers[i]);
 206   }
 207
 208   if (idx + length != list->n_buffers) {
 209     memmove (&list->buffers[idx], &list->buffers[idx + length],
 210         (list->n_buffers - (idx + length)) * sizeof (void *));
 211   }
 212
 213   list->n_buffers -= length;
 214 }
 215
 216 /**
 217  * gst_buffer_list_foreach:
 218  * @list: a #GstBufferList
 219  * @func: (scope call): a #GstBufferListFunc to call
 220  * @user_data: (closure): user data passed to @func
 221  *
 222  * Call @func with @data for each buffer in @list.
 223  *
 224  * @func can modify the passed buffer pointer or its contents. The return value
 225  * of @func define if this function returns or if the remaining buffers in
 226  * the list should be skipped.
 227  *
 228  * Returns: %TRUE when @func returned %TRUE for each buffer in @list or when
 229  * @list is empty.
 230  */
 231 gboolean
 232 gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
 233     gpointer user_data)
 234 {
 235   guint i, len;
 236   gboolean ret = TRUE;
 237
 238   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), FALSE);
 239   g_return_val_if_fail (func != NULL, FALSE);
 240
 241   len = list->n_buffers;
 242   for (i = 0; i < len;) {
 243     GstBuffer *buf, *buf_ret;
 244
 245     buf = buf_ret = list->buffers[i];
 246     ret = func (&buf_ret, i, user_data);
 247
 248     /* Check if the function changed the buffer */
 249     if (buf != buf_ret) {
 250       if (buf_ret == NULL) {
 251         gst_buffer_list_remove_range_internal (list, i, 1, FALSE);
 252         --len;
 253       } else {
 254         list->buffers[i] = buf_ret;
 255       }
 256     }
 257
 258     if (!ret)
 259       break;
 260
 261     /* If the buffer was not removed by func go to the next buffer */
 262     if (buf_ret != NULL)
 263       i++;
 264   }
 265   return ret;
 266 }
 267
 268 /**
 269  * gst_buffer_list_get:
 270  * @list: a #GstBufferList
 271  * @idx: the index
 272  *
 273  * Get the buffer at @idx.
 274  *
 275  * Returns: (transfer none) (nullable): the buffer at @idx in @group
 276  *     or %NULL when there is no buffer. The buffer remains valid as
 277  *     long as @list is valid and buffer is not removed from the list.
 278  */
 279 GstBuffer *
 280 gst_buffer_list_get (GstBufferList * list, guint idx)
 281 {
 282   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 283   g_return_val_if_fail (idx < list->n_buffers, NULL);
 284
 285   return list->buffers[idx];
 286 }
 287
 288 /**
 289  * gst_buffer_list_add:
 290  * @l: a #GstBufferList
 291  * @b: a #GstBuffer
 292  *
 293  * Append @b at the end of @l.
 294  */
 295 /**
 296  * gst_buffer_list_insert:
 297  * @list: a #GstBufferList
 298  * @idx: the index
 299  * @buffer: (transfer full): a #GstBuffer
 300  *
 301  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 302  * this new buffer.
 303  *
 304  * A -1 value for @idx will append the buffer at the end.
 305  */
 306 void
 307 gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer)
 308 {
 309   guint want_alloc;
 310
 311   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 312   g_return_if_fail (buffer != NULL);
 313   g_return_if_fail (gst_buffer_list_is_writable (list));
 314
 315   if (idx == -1 && list->n_buffers < list->n_allocated) {
 316     list->buffers[list->n_buffers++] = buffer;
 317     return;
 318   }
 319
 320   if (idx == -1 || idx > list->n_buffers)
 321     idx = list->n_buffers;
 322
 323   want_alloc = list->n_buffers + 1;
 324
 325   if (want_alloc > list->n_allocated) {
 326     want_alloc = MAX (GST_ROUND_UP_16 (want_alloc), list->n_allocated * 2);
 327
 328     if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list)) {
 329       list->buffers = g_renew (GstBuffer *, list->buffers, want_alloc);
 330     } else {
 331       list->buffers = g_new0 (GstBuffer *, want_alloc);
 332       memcpy (list->buffers, &list->arr[0], list->n_buffers * sizeof (void *));
 333       GST_CAT_LOG (GST_CAT_PERFORMANCE, "exceeding pre-alloced array");
 334     }
 335
 336     list->n_allocated = want_alloc;
 337   }
 338
 339   if (idx < list->n_buffers) {
 340     memmove (&list->buffers[idx + 1], &list->buffers[idx],
 341         (list->n_buffers - idx) * sizeof (void *));
 342   }
 343
 344   ++list->n_buffers;
 345   list->buffers[idx] = buffer;
 346 }
 347
 348 /**
 349  * gst_buffer_list_remove:
 350  * @list: a #GstBufferList
 351  * @idx: the index
 352  * @length: the amount to remove
 353  *
 354  * Remove @length buffers starting from @idx in @list. The following buffers
 355  * are moved to close the gap.
 356  */
 357 void
 358 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 359 {
 360   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 361   g_return_if_fail (idx < list->n_buffers);
 362   g_return_if_fail (idx + length <= list->n_buffers);
 363   g_return_if_fail (gst_buffer_list_is_writable (list));
 364
 365   gst_buffer_list_remove_range_internal (list, idx, length, TRUE);
 366 }