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   if (size == 0)
 153     size = 1;
 154
 155   n_allocated = GST_ROUND_UP_16 (size);
 156
 157   slice_size = sizeof (GstBufferList) + (n_allocated - 1) * sizeof (gpointer);
 158
 159   list = g_slice_alloc0 (slice_size);
 160
 161   GST_LOG ("new %p", list);
 162
 163   gst_buffer_list_init (list, n_allocated, slice_size);
 164
 165   return list;
 166 }
 167
 168 /**
 169  * gst_buffer_list_new:
 170  *
 171  * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
 172  * the returned #GstBufferList.
 173  *
 174  * Free-function: gst_buffer_list_unref
 175  *
 176  * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
 177  *     after usage.
 178  */
 179 GstBufferList *
 180 gst_buffer_list_new (void)
 181 {
 182   return gst_buffer_list_new_sized (8);
 183 }
 184
 185 /**
 186  * gst_buffer_list_length:
 187  * @list: a #GstBufferList
 188  *
 189  * Returns the number of buffers in @list.
 190  *
 191  * Returns: the number of buffers in the buffer list
 192  */
 193 guint
 194 gst_buffer_list_length (GstBufferList * list)
 195 {
 196   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 197
 198   return list->n_buffers;
 199 }
 200
 201 static inline void
 202 gst_buffer_list_remove_range_internal (GstBufferList * list, guint idx,
 203     guint length, gboolean unref_old)
 204 {
 205   guint i;
 206
 207   if (unref_old) {
 208     for (i = idx; i < idx + length; ++i)
 209       gst_buffer_unref (list->buffers[i]);
 210   }
 211
 212   if (idx + length != list->n_buffers) {
 213     memmove (&list->buffers[idx], &list->buffers[idx + length],
 214         (list->n_buffers - (idx + length)) * sizeof (void *));
 215   }
 216
 217   list->n_buffers -= length;
 218 }
 219
 220 /**
 221  * gst_buffer_list_foreach:
 222  * @list: a #GstBufferList
 223  * @func: (scope call): a #GstBufferListFunc to call
 224  * @user_data: (closure): user data passed to @func
 225  *
 226  * Call @func with @data for each buffer in @list.
 227  *
 228  * @func can modify the passed buffer pointer or its contents. The return value
 229  * of @func define if this function returns or if the remaining buffers in
 230  * the list should be skipped.
 231  *
 232  * Returns: %TRUE when @func returned %TRUE for each buffer in @list or when
 233  * @list is empty.
 234  */
 235 gboolean
 236 gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
 237     gpointer user_data)
 238 {
 239   guint i, len;
 240   gboolean ret = TRUE;
 241
 242   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), FALSE);
 243   g_return_val_if_fail (func != NULL, FALSE);
 244
 245   len = list->n_buffers;
 246   for (i = 0; i < len;) {
 247     GstBuffer *buf, *buf_ret;
 248
 249     buf = buf_ret = list->buffers[i];
 250     ret = func (&buf_ret, i, user_data);
 251
 252     /* Check if the function changed the buffer */
 253     if (buf != buf_ret) {
 254       if (buf_ret == NULL) {
 255         gst_buffer_list_remove_range_internal (list, i, 1, FALSE);
 256         --len;
 257       } else {
 258         list->buffers[i] = buf_ret;
 259       }
 260     }
 261
 262     if (!ret)
 263       break;
 264
 265     /* If the buffer was not removed by func go to the next buffer */
 266     if (buf_ret != NULL)
 267       i++;
 268   }
 269   return ret;
 270 }
 271
 272 /**
 273  * gst_buffer_list_get:
 274  * @list: a #GstBufferList
 275  * @idx: the index
 276  *
 277  * Get the buffer at @idx.
 278  *
 279  * You must make sure that @idx does not exceed the number of
 280  * buffers available.
 281  *
 282  * Returns: (transfer none) (nullable): the buffer at @idx in @group
 283  *     or %NULL when there is no buffer. The buffer remains valid as
 284  *     long as @list is valid and buffer is not removed from the list.
 285  */
 286 GstBuffer *
 287 gst_buffer_list_get (GstBufferList * list, guint idx)
 288 {
 289   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 290   g_return_val_if_fail (idx < list->n_buffers, NULL);
 291
 292   return list->buffers[idx];
 293 }
 294
 295 /**
 296  * gst_buffer_list_get_writable:
 297  * @list: a (writable) #GstBufferList
 298  * @idx: the index
 299  *
 300  * Gets the buffer at @idx, ensuring it is a writable buffer.
 301  *
 302  * You must make sure that @idx does not exceed the number of
 303  * buffers available.
 304  *
 305  * Returns: (transfer none) (nullable): the buffer at @idx in @group.
 306  *     The returned  buffer remains valid as long as @list is valid and
 307  *     the buffer is not removed from the list.
 308  *
 309  * Since: 1.14
 310  */
 311 GstBuffer *
 312 gst_buffer_list_get_writable (GstBufferList * list, guint idx)
 313 {
 314   GstBuffer **p_buf;
 315
 316   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 317   g_return_val_if_fail (gst_buffer_list_is_writable (list), NULL);
 318   g_return_val_if_fail (idx < list->n_buffers, NULL);
 319
 320   p_buf = &list->buffers[idx];
 321   return (*p_buf = gst_buffer_make_writable (*p_buf));
 322 }
 323
 324 /**
 325  * gst_buffer_list_add:
 326  * @l: a #GstBufferList
 327  * @b: a #GstBuffer
 328  *
 329  * Append @b at the end of @l.
 330  */
 331 /**
 332  * gst_buffer_list_insert:
 333  * @list: a #GstBufferList
 334  * @idx: the index
 335  * @buffer: (transfer full): a #GstBuffer
 336  *
 337  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 338  * this new buffer.
 339  *
 340  * A -1 value for @idx will append the buffer at the end.
 341  */
 342 void
 343 gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer)
 344 {
 345   guint want_alloc;
 346
 347   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 348   g_return_if_fail (buffer != NULL);
 349   g_return_if_fail (gst_buffer_list_is_writable (list));
 350
 351   if (idx == -1 && list->n_buffers < list->n_allocated) {
 352     list->buffers[list->n_buffers++] = buffer;
 353     return;
 354   }
 355
 356   if (idx == -1 || idx > list->n_buffers)
 357     idx = list->n_buffers;
 358
 359   want_alloc = list->n_buffers + 1;
 360
 361   if (want_alloc > list->n_allocated) {
 362     want_alloc = MAX (GST_ROUND_UP_16 (want_alloc), list->n_allocated * 2);
 363
 364     if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list)) {
 365       list->buffers = g_renew (GstBuffer *, list->buffers, want_alloc);
 366     } else {
 367       list->buffers = g_new0 (GstBuffer *, want_alloc);
 368       memcpy (list->buffers, &list->arr[0], list->n_buffers * sizeof (void *));
 369       GST_CAT_LOG (GST_CAT_PERFORMANCE, "exceeding pre-alloced array");
 370     }
 371
 372     list->n_allocated = want_alloc;
 373   }
 374
 375   if (idx < list->n_buffers) {
 376     memmove (&list->buffers[idx + 1], &list->buffers[idx],
 377         (list->n_buffers - idx) * sizeof (void *));
 378   }
 379
 380   ++list->n_buffers;
 381   list->buffers[idx] = buffer;
 382 }
 383
 384 /**
 385  * gst_buffer_list_remove:
 386  * @list: a #GstBufferList
 387  * @idx: the index
 388  * @length: the amount to remove
 389  *
 390  * Remove @length buffers starting from @idx in @list. The following buffers
 391  * are moved to close the gap.
 392  */
 393 void
 394 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 395 {
 396   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 397   g_return_if_fail (idx < list->n_buffers);
 398   g_return_if_fail (idx + length <= list->n_buffers);
 399   g_return_if_fail (gst_buffer_list_is_writable (list));
 400
 401   gst_buffer_list_remove_range_internal (list, idx, length, TRUE);
 402 }
 403
 404 /**
 405  * gst_buffer_list_copy_deep:
 406  * @list: a #GstBufferList
 407  *
 408  * Create a copy of the given buffer list. This will make a newly allocated
 409  * copy of the buffer that the source buffer list contains.
 410  *
 411  * Returns: (transfer full): a new copy of @list.
 412  *
 413  * Since: 1.6
 414  */
 415 GstBufferList *
 416 gst_buffer_list_copy_deep (const GstBufferList * list)
 417 {
 418   guint i, len;
 419   GstBufferList *result = NULL;
 420
 421   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 422
 423   result = gst_buffer_list_new ();
 424
 425   len = list->n_buffers;
 426   for (i = 0; i < len; i++) {
 427     GstBuffer *old = list->buffers[i];
 428     GstBuffer *new = gst_buffer_copy_deep (old);
 429
 430     if (G_LIKELY (new)) {
 431       gst_buffer_list_insert (result, i, new);
 432     } else {
 433       g_warning
 434           ("Failed to deep copy buffer %p while deep "
 435           "copying buffer list %p. Buffer list copy "
 436           "will be incomplete", old, list);
 437     }
 438   }
 439
 440   return result;
 441 }
 442
 443 /**
 444  * gst_buffer_list_calculate_size:
 445  * @list: a #GstBufferList
 446  *
 447  * Calculates the size of the data contained in buffer list by adding the
 448  * size of all buffers.
 449  *
 450  * Returns: the size of the data contained in buffer list in bytes.
 451  *
 452  * Since: 1.14
 453  */
 454 gsize
 455 gst_buffer_list_calculate_size (GstBufferList * list)
 456 {
 457   GstBuffer **buffers;
 458   gsize size = 0;
 459   guint i, n;
 460
 461   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), 0);
 462
 463   n = list->n_buffers;
 464   buffers = list->buffers;
 465
 466   for (i = 0; i < n; ++i)
 467     size += gst_buffer_get_size (buffers[i]);
 468
 469   return size;
 470 }