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     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (copy->buffers[i]),
  94         GST_MINI_OBJECT_CAST (copy));
  95   }
  96
  97   copy->n_buffers = len;
  98
  99   return copy;
 100 }
 101
 102 static void
 103 _gst_buffer_list_free (GstBufferList * list)
 104 {
 105   guint i, len;
 106   gsize slice_size;
 107
 108   GST_LOG ("free %p", list);
 109
 110   /* unrefs all buffers too */
 111   len = list->n_buffers;
 112   for (i = 0; i < len; i++) {
 113     gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (list->buffers[i]),
 114         GST_MINI_OBJECT_CAST (list));
 115     gst_buffer_unref (list->buffers[i]);
 116   }
 117
 118   if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list))
 119     g_free (list->buffers);
 120
 121   slice_size = list->slice_size;
 122
 123 #ifdef USE_POISONING
 124   memset (list, 0xff, slice_size);
 125 #endif
 126
 127   g_slice_free1 (slice_size, list);
 128 }
 129
 130 static void
 131 gst_buffer_list_init (GstBufferList * list, guint n_allocated, gsize slice_size)
 132 {
 133   gst_mini_object_init (GST_MINI_OBJECT_CAST (list), 0, _gst_buffer_list_type,
 134       (GstMiniObjectCopyFunction) _gst_buffer_list_copy, NULL,
 135       (GstMiniObjectFreeFunction) _gst_buffer_list_free);
 136
 137   list->buffers = &list->arr[0];
 138   list->n_buffers = 0;
 139   list->n_allocated = n_allocated;
 140   list->slice_size = slice_size;
 141
 142   GST_LOG ("init %p", list);
 143 }
 144
 145 /**
 146  * gst_buffer_list_new_sized:
 147  * @size: an initial reserved size
 148  *
 149  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 150  * the returned #GstBufferList. The list will have @size space preallocated so
 151  * that memory reallocations can be avoided.
 152  *
 153  * Free-function: gst_buffer_list_unref
 154  *
 155  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 156  *     after usage.
 157  */
 158 GstBufferList *
 159 gst_buffer_list_new_sized (guint size)
 160 {
 161   GstBufferList *list;
 162   gsize slice_size;
 163   guint n_allocated;
 164
 165   if (size == 0)
 166     size = 1;
 167
 168   n_allocated = GST_ROUND_UP_16 (size);
 169
 170   slice_size = sizeof (GstBufferList) + (n_allocated - 1) * sizeof (gpointer);
 171
 172   list = g_slice_alloc0 (slice_size);
 173
 174   GST_LOG ("new %p", list);
 175
 176   gst_buffer_list_init (list, n_allocated, slice_size);
 177
 178   return list;
 179 }
 180
 181 /**
 182  * gst_buffer_list_new:
 183  *
 184  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 185  * the returned #GstBufferList.
 186  *
 187  * Free-function: gst_buffer_list_unref
 188  *
 189  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 190  *     after usage.
 191  */
 192 GstBufferList *
 193 gst_buffer_list_new (void)
 194 {
 195   return gst_buffer_list_new_sized (8);
 196 }
 197
 198 /**
 199  * gst_buffer_list_length:
 200  * @list: a #GstBufferList
 201  *
 202  * Returns the number of buffers in @list.
 203  *
 204  * Returns: the number of buffers in the buffer list
 205  */
 206 guint
 207 gst_buffer_list_length (GstBufferList * list)
 208 {
 209   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 210
 211   return list->n_buffers;
 212 }
 213
 214 static inline void
 215 gst_buffer_list_remove_range_internal (GstBufferList * list, guint idx,
 216     guint length, gboolean unref_old)
 217 {
 218   guint i;
 219
 220   if (unref_old) {
 221     for (i = idx; i < idx + length; ++i) {
 222       gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (list->buffers[i]),
 223           GST_MINI_OBJECT_CAST (list));
 224       gst_buffer_unref (list->buffers[i]);
 225     }
 226   }
 227
 228   if (idx + length != list->n_buffers) {
 229     memmove (&list->buffers[idx], &list->buffers[idx + length],
 230         (list->n_buffers - (idx + length)) * sizeof (void *));
 231   }
 232
 233   list->n_buffers -= length;
 234 }
 235
 236 /**
 237  * gst_buffer_list_foreach:
 238  * @list: a #GstBufferList
 239  * @func: (scope call): a #GstBufferListFunc to call
 240  * @user_data: (closure): user data passed to @func
 241  *
 242  * Call @func with @data for each buffer in @list.
 243  *
 244  * @func can modify the passed buffer pointer or its contents. The return value
 245  * of @func define if this function returns or if the remaining buffers in
 246  * the list should be skipped.
 247  *
 248  * Returns: %TRUE when @func returned %TRUE for each buffer in @list or when
 249  * @list is empty.
 250  */
 251 gboolean
 252 gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
 253     gpointer user_data)
 254 {
 255   guint i, len;
 256   gboolean ret = TRUE;
 257   gboolean list_was_writable, first_warning = TRUE;
 258
 259   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), FALSE);
 260   g_return_val_if_fail (func != NULL, FALSE);
 261
 262   list_was_writable = gst_buffer_list_is_writable (list);
 263
 264   len = list->n_buffers;
 265   for (i = 0; i < len;) {
 266     GstBuffer *buf, *buf_ret;
 267     gboolean was_writable;
 268
 269     buf = buf_ret = list->buffers[i];
 270
 271     /* If the buffer is writable, we remove us as parent for now to
 272      * allow the callback to destroy the buffer. If we get the buffer
 273      * back, we add ourselves as parent again.
 274      *
 275      * Non-writable buffers just get another reference as they were not
 276      * writable to begin with, and they would possibly become writable
 277      * by removing ourselves as parent
 278      */
 279     was_writable = list_was_writable && gst_buffer_is_writable (buf);
 280
 281     if (was_writable)
 282       gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (buf),
 283           GST_MINI_OBJECT_CAST (list));
 284     else
 285       gst_buffer_ref (buf);
 286
 287     ret = func (&buf_ret, i, user_data);
 288
 289     /* Check if the function changed the buffer */
 290     if (buf != buf_ret) {
 291       /* If the list was not writable but the callback was actually changing
 292        * our buffer, then it wouldn't have been allowed to do so.
 293        *
 294        * Fortunately we still have a reference to the old buffer in that case
 295        * and just not modify the list, unref the new buffer (if any) and warn
 296        * about this */
 297       if (!list_was_writable) {
 298         if (first_warning) {
 299           g_critical
 300               ("gst_buffer_list_foreach: non-writable list %p was changed from callback",
 301               list);
 302           first_warning = FALSE;
 303         }
 304         if (buf_ret)
 305           gst_buffer_unref (buf_ret);
 306       } else if (buf_ret == NULL) {
 307         gst_buffer_list_remove_range_internal (list, i, 1, !was_writable);
 308         --len;
 309       } else {
 310         if (!was_writable)
 311           gst_buffer_unref (buf);
 312
 313         list->buffers[i] = buf_ret;
 314         gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (buf_ret),
 315             GST_MINI_OBJECT_CAST (list));
 316       }
 317     } else {
 318       if (was_writable)
 319         gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (buf),
 320             GST_MINI_OBJECT_CAST (list));
 321       else
 322         gst_buffer_unref (buf);
 323     }
 324
 325     if (!ret)
 326       break;
 327
 328     /* If the buffer was not removed by func go to the next buffer */
 329     if (buf_ret != NULL)
 330       i++;
 331   }
 332   return ret;
 333 }
 334
 335 /**
 336  * gst_buffer_list_get:
 337  * @list: a #GstBufferList
 338  * @idx: the index
 339  *
 340  * Get the buffer at @idx.
 341  *
 342  * You must make sure that @idx does not exceed the number of
 343  * buffers available.
 344  *
 345  * Returns: (transfer none) (nullable): the buffer at @idx in @group
 346  *     or %NULL when there is no buffer. The buffer remains valid as
 347  *     long as @list is valid and buffer is not removed from the list.
 348  */
 349 GstBuffer *
 350 gst_buffer_list_get (GstBufferList * list, guint idx)
 351 {
 352   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 353   g_return_val_if_fail (idx < list->n_buffers, NULL);
 354
 355   return list->buffers[idx];
 356 }
 357
 358 /**
 359  * gst_buffer_list_get_writable:
 360  * @list: a (writable) #GstBufferList
 361  * @idx: the index
 362  *
 363  * Gets the buffer at @idx, ensuring it is a writable buffer.
 364  *
 365  * You must make sure that @idx does not exceed the number of
 366  * buffers available.
 367  *
 368  * Returns: (transfer none) (nullable): the buffer at @idx in @group.
 369  *     The returned  buffer remains valid as long as @list is valid and
 370  *     the buffer is not removed from the list.
 371  *
 372  * Since: 1.14
 373  */
 374 GstBuffer *
 375 gst_buffer_list_get_writable (GstBufferList * list, guint idx)
 376 {
 377   GstBuffer *new_buf;
 378
 379   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 380   g_return_val_if_fail (gst_buffer_list_is_writable (list), NULL);
 381   g_return_val_if_fail (idx < list->n_buffers, NULL);
 382
 383   /* We have to implement this manually here to correctly add/remove the
 384    * parent */
 385   if (gst_buffer_is_writable (list->buffers[idx]))
 386     return list->buffers[idx];
 387
 388   gst_mini_object_remove_parent (GST_MINI_OBJECT_CAST (list->buffers[idx]),
 389       GST_MINI_OBJECT_CAST (list));
 390   new_buf = gst_buffer_copy (list->buffers[idx]);
 391   gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (new_buf),
 392       GST_MINI_OBJECT_CAST (list));
 393   gst_buffer_unref (list->buffers[idx]);
 394   list->buffers[idx] = new_buf;
 395
 396   return new_buf;
 397 }
 398
 399 /**
 400  * gst_buffer_list_add:
 401  * @l: a #GstBufferList
 402  * @b: a #GstBuffer
 403  *
 404  * Append @b at the end of @l.
 405  */
 406 /**
 407  * gst_buffer_list_insert:
 408  * @list: a #GstBufferList
 409  * @idx: the index
 410  * @buffer: (transfer full): a #GstBuffer
 411  *
 412  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 413  * this new buffer.
 414  *
 415  * A -1 value for @idx will append the buffer at the end.
 416  */
 417 void
 418 gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer)
 419 {
 420   guint want_alloc;
 421
 422   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 423   g_return_if_fail (buffer != NULL);
 424   g_return_if_fail (gst_buffer_list_is_writable (list));
 425
 426   if (idx == -1 && list->n_buffers < list->n_allocated) {
 427     gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (buffer),
 428         GST_MINI_OBJECT_CAST (list));
 429     list->buffers[list->n_buffers++] = buffer;
 430     return;
 431   }
 432
 433   if (idx == -1 || idx > list->n_buffers)
 434     idx = list->n_buffers;
 435
 436   want_alloc = list->n_buffers + 1;
 437
 438   if (want_alloc > list->n_allocated) {
 439     want_alloc = MAX (GST_ROUND_UP_16 (want_alloc), list->n_allocated * 2);
 440
 441     if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list)) {
 442       list->buffers = g_renew (GstBuffer *, list->buffers, want_alloc);
 443     } else {
 444       list->buffers = g_new0 (GstBuffer *, want_alloc);
 445       memcpy (list->buffers, &list->arr[0], list->n_buffers * sizeof (void *));
 446       GST_CAT_LOG (GST_CAT_PERFORMANCE, "exceeding pre-alloced array");
 447     }
 448
 449     list->n_allocated = want_alloc;
 450   }
 451
 452   if (idx < list->n_buffers) {
 453     memmove (&list->buffers[idx + 1], &list->buffers[idx],
 454         (list->n_buffers - idx) * sizeof (void *));
 455   }
 456
 457   ++list->n_buffers;
 458   list->buffers[idx] = buffer;
 459   gst_mini_object_add_parent (GST_MINI_OBJECT_CAST (buffer),
 460       GST_MINI_OBJECT_CAST (list));
 461 }
 462
 463 /**
 464  * gst_buffer_list_remove:
 465  * @list: a #GstBufferList
 466  * @idx: the index
 467  * @length: the amount to remove
 468  *
 469  * Remove @length buffers starting from @idx in @list. The following buffers
 470  * are moved to close the gap.
 471  */
 472 void
 473 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 474 {
 475   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 476   g_return_if_fail (idx < list->n_buffers);
 477   g_return_if_fail (idx + length <= list->n_buffers);
 478   g_return_if_fail (gst_buffer_list_is_writable (list));
 479
 480   gst_buffer_list_remove_range_internal (list, idx, length, TRUE);
 481 }
 482
 483 /**
 484  * gst_buffer_list_copy_deep:
 485  * @list: a #GstBufferList
 486  *
 487  * Create a copy of the given buffer list. This will make a newly allocated
 488  * copy of the buffer that the source buffer list contains.
 489  *
 490  * Returns: (transfer full): a new copy of @list.
 491  *
 492  * Since: 1.6
 493  */
 494 GstBufferList *
 495 gst_buffer_list_copy_deep (const GstBufferList * list)
 496 {
 497   guint i, len;
 498   GstBufferList *result = NULL;
 499
 500   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 501
 502   result = gst_buffer_list_new ();
 503
 504   len = list->n_buffers;
 505   for (i = 0; i < len; i++) {
 506     GstBuffer *old = list->buffers[i];
 507     GstBuffer *new = gst_buffer_copy_deep (old);
 508
 509     if (G_LIKELY (new)) {
 510       gst_buffer_list_insert (result, i, new);
 511     } else {
 512       g_warning
 513           ("Failed to deep copy buffer %p while deep "
 514           "copying buffer list %p. Buffer list copy "
 515           "will be incomplete", old, list);
 516     }
 517   }
 518
 519   return result;
 520 }
 521
 522 /**
 523  * gst_buffer_list_calculate_size:
 524  * @list: a #GstBufferList
 525  *
 526  * Calculates the size of the data contained in buffer list by adding the
 527  * size of all buffers.
 528  *
 529  * Returns: the size of the data contained in buffer list in bytes.
 530  *
 531  * Since: 1.14
 532  */
 533 gsize
 534 gst_buffer_list_calculate_size (GstBufferList * list)
 535 {
 536   GstBuffer **buffers;
 537   gsize size = 0;
 538   guint i, n;
 539
 540   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 541
 542   n = list->n_buffers;
 543   buffers = list->buffers;
 544
 545   for (i = 0; i < n; ++i)
 546     size += gst_buffer_get_size (buffers[i]);
 547
 548   return size;
 549 }