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