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  * You must make sure that @idx does not exceed the number of
 277  * buffers available.
 278  *
 279  * Returns: (transfer none) (nullable): the buffer at @idx in @group
 280  *     or %NULL when there is no buffer. The buffer remains valid as
 281  *     long as @list is valid and buffer is not removed from the list.
 282  */
 283 GstBuffer *
 284 gst_buffer_list_get (GstBufferList * list, guint idx)
 285 {
 286   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 287   g_return_val_if_fail (idx < list->n_buffers, NULL);
 288
 289   return list->buffers[idx];
 290 }
 291
 292 /**
 293  * gst_buffer_list_get_writable:
 294  * @list: a (writable) #GstBufferList
 295  * @idx: the index
 296  *
 297  * Gets the buffer at @idx, ensuring it is a writable buffer.
 298  *
 299  * You must make sure that @idx does not exceed the number of
 300  * buffers available.
 301  *
 302  * Returns: (transfer none) (nullable): the buffer at @idx in @group.
 303  *     The returned  buffer remains valid as long as @list is valid and
 304  *     the buffer is not removed from the list.
 305  *
 306  * Since: 1.14
 307  */
 308 GstBuffer *
 309 gst_buffer_list_get_writable (GstBufferList * list, guint idx)
 310 {
 311   GstBuffer **p_buf;
 312
 313   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 314   g_return_val_if_fail (gst_buffer_list_is_writable (list), NULL);
 315   g_return_val_if_fail (idx < list->n_buffers, NULL);
 316
 317   p_buf = &list->buffers[idx];
 318   return (*p_buf = gst_buffer_make_writable (*p_buf));
 319 }
 320
 321 /**
 322  * gst_buffer_list_add:
 323  * @l: a #GstBufferList
 324  * @b: a #GstBuffer
 325  *
 326  * Append @b at the end of @l.
 327  */
 328 /**
 329  * gst_buffer_list_insert:
 330  * @list: a #GstBufferList
 331  * @idx: the index
 332  * @buffer: (transfer full): a #GstBuffer
 333  *
 334  * Insert @buffer at @idx in @list. Other buffers are moved to make room for
 335  * this new buffer.
 336  *
 337  * A -1 value for @idx will append the buffer at the end.
 338  */
 339 void
 340 gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer)
 341 {
 342   guint want_alloc;
 343
 344   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 345   g_return_if_fail (buffer != NULL);
 346   g_return_if_fail (gst_buffer_list_is_writable (list));
 347
 348   if (idx == -1 && list->n_buffers < list->n_allocated) {
 349     list->buffers[list->n_buffers++] = buffer;
 350     return;
 351   }
 352
 353   if (idx == -1 || idx > list->n_buffers)
 354     idx = list->n_buffers;
 355
 356   want_alloc = list->n_buffers + 1;
 357
 358   if (want_alloc > list->n_allocated) {
 359     want_alloc = MAX (GST_ROUND_UP_16 (want_alloc), list->n_allocated * 2);
 360
 361     if (GST_BUFFER_LIST_IS_USING_DYNAMIC_ARRAY (list)) {
 362       list->buffers = g_renew (GstBuffer *, list->buffers, want_alloc);
 363     } else {
 364       list->buffers = g_new0 (GstBuffer *, want_alloc);
 365       memcpy (list->buffers, &list->arr[0], list->n_buffers * sizeof (void *));
 366       GST_CAT_LOG (GST_CAT_PERFORMANCE, "exceeding pre-alloced array");
 367     }
 368
 369     list->n_allocated = want_alloc;
 370   }
 371
 372   if (idx < list->n_buffers) {
 373     memmove (&list->buffers[idx + 1], &list->buffers[idx],
 374         (list->n_buffers - idx) * sizeof (void *));
 375   }
 376
 377   ++list->n_buffers;
 378   list->buffers[idx] = buffer;
 379 }
 380
 381 /**
 382  * gst_buffer_list_remove:
 383  * @list: a #GstBufferList
 384  * @idx: the index
 385  * @length: the amount to remove
 386  *
 387  * Remove @length buffers starting from @idx in @list. The following buffers
 388  * are moved to close the gap.
 389  */
 390 void
 391 gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
 392 {
 393   g_return_if_fail (GST_IS_BUFFER_LIST (list));
 394   g_return_if_fail (idx < list->n_buffers);
 395   g_return_if_fail (idx + length <= list->n_buffers);
 396   g_return_if_fail (gst_buffer_list_is_writable (list));
 397
 398   gst_buffer_list_remove_range_internal (list, idx, length, TRUE);
 399 }
 400
 401 /**
 402  * gst_buffer_list_copy_deep:
 403  * @list: a #GstBufferList
 404  *
 405  * Create a copy of the given buffer list. This will make a newly allocated
 406  * copy of the buffer that the source buffer list contains.
 407  *
 408  * Returns: (transfer full): a new copy of @list.
 409  *
 410  * Since: 1.6
 411  */
 412 GstBufferList *
 413 gst_buffer_list_copy_deep (const GstBufferList * list)
 414 {
 415   guint i, len;
 416   GstBufferList *result = NULL;
 417
 418   g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
 419
 420   result = gst_buffer_list_new ();
 421
 422   len = list->n_buffers;
 423   for (i = 0; i < len; i++) {
 424     GstBuffer *old = list->buffers[i];
 425     GstBuffer *new = gst_buffer_copy_deep (old);
 426
 427     if (G_LIKELY (new)) {
 428       gst_buffer_list_insert (result, i, new);
 429     } else {
 430       g_warning
 431           ("Failed to deep copy buffer %p while deep "
 432           "copying buffer list %p. Buffer list copy "
 433           "will be incomplete", old, list);
 434     }
 435   }
 436
 437   return result;
 438 }