libs/gst/base/gstadapter.c

   1 /* GStreamer
   2  * Copyright (C) 2004 Benjamin Otte <otte@gnome.org>
   3  *               2005 Wim Taymans <wim@fluendo.com>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * SECTION:gstadapter
  23  * @short_description: adapts incoming data on a sink pad into chunks of N bytes
  24  *
  25  * This class is for elements that receive buffers in an undesired size.
  26  * While for example raw video contains one image per buffer, the same is not
  27  * true for a lot of other formats, especially those that come directly from
  28  * a file. So if you have undefined buffer sizes and require a specific size,
  29  * this object is for you.
  30  *
  31  * An adapter is created with gst_adapter_new(). It can be freed again with
  32  * g_object_unref().
  33  *
  34  * The theory of operation is like this: All buffers received are put
  35  * into the adapter using gst_adapter_push() and the data is then read back
  36  * in chunks of the desired size using gst_adapter_map()/gst_adapter_unmap()
  37  * and/or gst_adapter_copy(). After the data has been processed, it is freed
  38  * using gst_adapter_unmap().
  39  *
  40  * Other methods such as gst_adapter_take() and gst_adapter_take_buffer()
  41  * combine gst_adapter_map() and gst_adapter_unmap() in one method and are
  42  * potentially more convenient for some use cases.
  43  *
  44  * For example, a sink pad's chain function that needs to pass data to a library
  45  * in 512-byte chunks could be implemented like this:
  46  * |[
  47  * static GstFlowReturn
  48  * sink_pad_chain (GstPad *pad, GstBuffer *buffer)
  49  * {
  50  *   MyElement *this;
  51  *   GstAdapter *adapter;
  52  *   GstFlowReturn ret = GST_FLOW_OK;
  53  *
  54  *   // will give the element an extra ref; remember to drop it
  55  *   this = MY_ELEMENT (gst_pad_get_parent (pad));
  56  *   adapter = this->adapter;
  57  *
  58  *   // put buffer into adapter
  59  *   gst_adapter_push (adapter, buffer);
  60  *   // while we can read out 512 bytes, process them
  61  *   while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) {
  62  *     const guint8 *data = gst_adapter_map (adapter, 512);
  63  *     // use flowreturn as an error value
  64  *     ret = my_library_foo (data);
  65  *     gst_adapter_unmap (adapter);
  66  *     gst_adapter_flush (adapter, 512);
  67  *   }
  68  *
  69  *   gst_object_unref (this);
  70  *   return ret;
  71  * }
  72  * ]|
  73  *
  74  * For another example, a simple element inside GStreamer that uses GstAdapter
  75  * is the libvisual element.
  76  *
  77  * An element using GstAdapter in its sink pad chain function should ensure that
  78  * when the FLUSH_STOP event is received, that any queued data is cleared using
  79  * gst_adapter_clear(). Data should also be cleared or processed on EOS and
  80  * when changing state from #GST_STATE_PAUSED to #GST_STATE_READY.
  81  *
  82  * Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might
  83  * need to clear the adapter after a discontinuity.
  84  *
  85  * Since 0.10.24, the adapter will keep track of the timestamps of the buffers
  86  * that were pushed. The last seen timestamp before the current position
  87  * can be queried with gst_adapter_prev_timestamp(). This function can
  88  * optionally return the amount of bytes between the start of the buffer that
  89  * carried the timestamp and the current adapter position. The distance is
  90  * useful when dealing with, for example, raw audio samples because it allows
  91  * you to calculate the timestamp of the current adapter position by using the
  92  * last seen timestamp and the amount of bytes since.
  93  *
  94  * A last thing to note is that while GstAdapter is pretty optimized,
  95  * merging buffers still might be an operation that requires a malloc() and
  96  * memcpy() operation, and these operations are not the fastest. Because of
  97  * this, some functions like gst_adapter_available_fast() are provided to help
  98  * speed up such cases should you want to. To avoid repeated memory allocations,
  99  * gst_adapter_copy() can be used to copy data into a (statically allocated)
 100  * user provided buffer.
 101  *
 102  * GstAdapter is not MT safe. All operations on an adapter must be serialized by
 103  * the caller. This is not normally a problem, however, as the normal use case
 104  * of GstAdapter is inside one pad's chain function, in which case access is
 105  * serialized via the pad's STREAM_LOCK.
 106  *
 107  * Note that gst_adapter_push() takes ownership of the buffer passed. Use
 108  * gst_buffer_ref() before pushing it into the adapter if you still want to
 109  * access the buffer later. The adapter will never modify the data in the
 110  * buffer pushed in it.
 111  *
 112  * Last reviewed on 2009-05-13 (0.10.24).
 113  */
 114
 115 #include <gst/gst_private.h>
 116 #include "gstadapter.h"
 117 #include <string.h>
 118
 119 /* default size for the assembled data buffer */
 120 #define DEFAULT_SIZE 4096
 121
 122 static void gst_adapter_flush_unchecked (GstAdapter * adapter, gsize flush);
 123
 124 GST_DEBUG_CATEGORY_STATIC (gst_adapter_debug);
 125 #define GST_CAT_DEFAULT gst_adapter_debug
 126
 127 #define GST_ADAPTER_GET_PRIVATE(obj)  \
 128    (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_ADAPTER, GstAdapterPrivate))
 129
 130 struct _GstAdapterPrivate
 131 {
 132   GstClockTime pts;
 133   guint64 pts_distance;
 134   GstClockTime dts;
 135   guint64 dts_distance;
 136
 137   gsize scan_offset;
 138   GSList *scan_entry;
 139
 140   gpointer cdata;
 141   gsize csize;
 142 };
 143
 144 #define _do_init \
 145   GST_DEBUG_CATEGORY_INIT (gst_adapter_debug, "adapter", 0, "object to splice and merge buffers to desired size")
 146 #define gst_adapter_parent_class parent_class
 147 G_DEFINE_TYPE_WITH_CODE (GstAdapter, gst_adapter, G_TYPE_OBJECT, _do_init);
 148
 149 static void gst_adapter_dispose (GObject * object);
 150 static void gst_adapter_finalize (GObject * object);
 151
 152 static void
 153 gst_adapter_class_init (GstAdapterClass * klass)
 154 {
 155   GObjectClass *object = G_OBJECT_CLASS (klass);
 156
 157   g_type_class_add_private (klass, sizeof (GstAdapterPrivate));
 158
 159   object->dispose = gst_adapter_dispose;
 160   object->finalize = gst_adapter_finalize;
 161 }
 162
 163 static void
 164 gst_adapter_init (GstAdapter * adapter)
 165 {
 166   adapter->priv = GST_ADAPTER_GET_PRIVATE (adapter);
 167   adapter->assembled_data = g_malloc (DEFAULT_SIZE);
 168   adapter->assembled_size = DEFAULT_SIZE;
 169   adapter->priv->pts = GST_CLOCK_TIME_NONE;
 170   adapter->priv->pts_distance = 0;
 171   adapter->priv->dts = GST_CLOCK_TIME_NONE;
 172   adapter->priv->dts_distance = 0;
 173 }
 174
 175 static void
 176 gst_adapter_dispose (GObject * object)
 177 {
 178   GstAdapter *adapter = GST_ADAPTER (object);
 179
 180   gst_adapter_clear (adapter);
 181
 182   GST_CALL_PARENT (G_OBJECT_CLASS, dispose, (object));
 183 }
 184
 185 static void
 186 gst_adapter_finalize (GObject * object)
 187 {
 188   GstAdapter *adapter = GST_ADAPTER (object);
 189
 190   g_free (adapter->assembled_data);
 191
 192   GST_CALL_PARENT (G_OBJECT_CLASS, finalize, (object));
 193 }
 194
 195 /**
 196  * gst_adapter_new:
 197  *
 198  * Creates a new #GstAdapter. Free with g_object_unref().
 199  *
 200  * Returns: (transfer full): a new #GstAdapter
 201  */
 202 GstAdapter *
 203 gst_adapter_new (void)
 204 {
 205   return g_object_newv (GST_TYPE_ADAPTER, 0, NULL);
 206 }
 207
 208 /**
 209  * gst_adapter_clear:
 210  * @adapter: a #GstAdapter
 211  *
 212  * Removes all buffers from @adapter.
 213  */
 214 void
 215 gst_adapter_clear (GstAdapter * adapter)
 216 {
 217   g_return_if_fail (GST_IS_ADAPTER (adapter));
 218
 219   if (adapter->priv->cdata) {
 220     gst_adapter_unmap (adapter);
 221   }
 222
 223   g_slist_foreach (adapter->buflist, (GFunc) gst_mini_object_unref, NULL);
 224   g_slist_free (adapter->buflist);
 225   adapter->buflist = NULL;
 226   adapter->buflist_end = NULL;
 227   adapter->size = 0;
 228   adapter->skip = 0;
 229   adapter->assembled_len = 0;
 230   adapter->priv->pts = GST_CLOCK_TIME_NONE;
 231   adapter->priv->pts_distance = 0;
 232   adapter->priv->dts = GST_CLOCK_TIME_NONE;
 233   adapter->priv->dts_distance = 0;
 234   adapter->priv->scan_offset = 0;
 235   adapter->priv->scan_entry = NULL;
 236 }
 237
 238 static inline void
 239 update_timestamps (GstAdapter * adapter, GstBuffer * buf)
 240 {
 241   GstClockTime pts, dts;
 242
 243   pts = GST_BUFFER_PTS (buf);
 244   if (GST_CLOCK_TIME_IS_VALID (pts)) {
 245     GST_LOG_OBJECT (adapter, "new pts %" GST_TIME_FORMAT, GST_TIME_ARGS (pts));
 246     adapter->priv->pts = pts;
 247     adapter->priv->pts_distance = 0;
 248   }
 249   dts = GST_BUFFER_DTS (buf);
 250   if (GST_CLOCK_TIME_IS_VALID (dts)) {
 251     GST_LOG_OBJECT (adapter, "new dts %" GST_TIME_FORMAT, GST_TIME_ARGS (dts));
 252     adapter->priv->dts = dts;
 253     adapter->priv->dts_distance = 0;
 254   }
 255 }
 256
 257 /* copy data into @dest, skipping @skip bytes from the head buffers */
 258 static void
 259 copy_into_unchecked (GstAdapter * adapter, guint8 * dest, gsize skip,
 260     gsize size)
 261 {
 262   GSList *g;
 263   GstBuffer *buf;
 264   gsize bsize, csize;
 265
 266   /* first step, do skipping */
 267   /* we might well be copying where we were scanning */
 268   if (adapter->priv->scan_entry && (adapter->priv->scan_offset <= skip)) {
 269     g = adapter->priv->scan_entry;
 270     skip -= adapter->priv->scan_offset;
 271   } else {
 272     g = adapter->buflist;
 273   }
 274   buf = g->data;
 275   bsize = gst_buffer_get_size (buf);
 276   while (G_UNLIKELY (skip >= bsize)) {
 277     skip -= bsize;
 278     g = g_slist_next (g);
 279     buf = g->data;
 280     bsize = gst_buffer_get_size (buf);
 281   }
 282   /* copy partial buffer */
 283   csize = MIN (bsize - skip, size);
 284   GST_DEBUG ("bsize %" G_GSIZE_FORMAT ", skip %" G_GSIZE_FORMAT ", csize %"
 285       G_GSIZE_FORMAT, bsize, skip, csize);
 286   gst_buffer_extract (buf, skip, dest, csize);
 287   size -= csize;
 288   dest += csize;
 289
 290   /* second step, copy remainder */
 291   while (size > 0) {
 292     g = g_slist_next (g);
 293     buf = g->data;
 294     bsize = gst_buffer_get_size (buf);
 295     if (G_LIKELY (bsize > 0)) {
 296       csize = MIN (bsize, size);
 297       gst_buffer_extract (buf, 0, dest, csize);
 298       size -= csize;
 299       dest += csize;
 300     }
 301   }
 302 }
 303
 304 /**
 305  * gst_adapter_push:
 306  * @adapter: a #GstAdapter
 307  * @buf: (transfer full): a #GstBuffer to add to queue in the adapter
 308  *
 309  * Adds the data from @buf to the data stored inside @adapter and takes
 310  * ownership of the buffer.
 311  */
 312 void
 313 gst_adapter_push (GstAdapter * adapter, GstBuffer * buf)
 314 {
 315   gsize size;
 316
 317   g_return_if_fail (GST_IS_ADAPTER (adapter));
 318   g_return_if_fail (GST_IS_BUFFER (buf));
 319
 320   size = gst_buffer_get_size (buf);
 321   adapter->size += size;
 322
 323   /* Note: merging buffers at this point is premature. */
 324   if (G_UNLIKELY (adapter->buflist == NULL)) {
 325     GST_LOG_OBJECT (adapter, "pushing first %" G_GSIZE_FORMAT " bytes", size);
 326     adapter->buflist = adapter->buflist_end = g_slist_append (NULL, buf);
 327     update_timestamps (adapter, buf);
 328   } else {
 329     /* Otherwise append to the end, and advance our end pointer */
 330     GST_LOG_OBJECT (adapter, "pushing %" G_GSIZE_FORMAT " bytes at end, "
 331         "size now %" G_GSIZE_FORMAT, size, adapter->size);
 332     adapter->buflist_end = g_slist_append (adapter->buflist_end, buf);
 333     adapter->buflist_end = g_slist_next (adapter->buflist_end);
 334   }
 335 }
 336
 337 /* Internal method only. Tries to merge buffers at the head of the queue
 338  * to form a single larger buffer of size 'size'. Only merges buffers that
 339  * where 'gst_buffer_is_span_fast' returns TRUE.
 340  *
 341  * Returns TRUE if it managed to merge anything.
 342  */
 343 static gboolean
 344 gst_adapter_try_to_merge_up (GstAdapter * adapter, gsize size)
 345 {
 346   GstBuffer *cur, *head;
 347   GSList *g;
 348   gboolean ret = FALSE;
 349   gsize hsize;
 350
 351   g = adapter->buflist;
 352   if (g == NULL)
 353     return FALSE;
 354
 355   head = g->data;
 356   g = g_slist_next (g);
 357
 358   /* How large do we want our head buffer? The requested size, plus whatever's
 359    * been skipped already */
 360   size += adapter->skip;
 361   hsize = gst_buffer_get_size (head);
 362
 363   while (g != NULL && hsize < size) {
 364     cur = g->data;
 365     if (!gst_buffer_is_span_fast (head, cur))
 366       return ret;
 367
 368     /* Merge the head buffer and the next in line */
 369     GST_LOG_OBJECT (adapter, "Merging buffers of size %" G_GSIZE_FORMAT " & %"
 370         G_GSIZE_FORMAT " in search of target %" G_GSIZE_FORMAT,
 371         hsize, gst_buffer_get_size (cur), size);
 372
 373     head = gst_buffer_join (head, cur);
 374     hsize = gst_buffer_get_size (head);
 375     ret = TRUE;
 376
 377     /* Delete the front list item, and store our new buffer in the 2nd list
 378      * item */
 379     adapter->buflist = g_slist_delete_link (adapter->buflist, adapter->buflist);
 380     g->data = head;
 381
 382     /* invalidate scan position */
 383     adapter->priv->scan_offset = 0;
 384     adapter->priv->scan_entry = NULL;
 385
 386     g = g_slist_next (g);
 387   }
 388
 389   return ret;
 390 }
 391
 392 /**
 393  * gst_adapter_map:
 394  * @adapter: a #GstAdapter
 395  * @size: the number of bytes to map/peek
 396  *
 397  * Gets the first @size bytes stored in the @adapter. The returned pointer is
 398  * valid until the next function is called on the adapter.
 399  *
 400  * Note that setting the returned pointer as the data of a #GstBuffer is
 401  * incorrect for general-purpose plugins. The reason is that if a downstream
 402  * element stores the buffer so that it has access to it outside of the bounds
 403  * of its chain function, the buffer will have an invalid data pointer after
 404  * your element flushes the bytes. In that case you should use
 405  * gst_adapter_take(), which returns a freshly-allocated buffer that you can set
 406  * as #GstBuffer malloc_data or the potentially more performant
 407  * gst_adapter_take_buffer().
 408  *
 409  * Returns #NULL if @size bytes are not available.
 410  *
 411  * Returns: (transfer none) (array length=size): a pointer to the first
 412  *     @size bytes of data, or NULL
 413  */
 414 gconstpointer
 415 gst_adapter_map (GstAdapter * adapter, gsize size)
 416 {
 417   GstBuffer *cur;
 418   gsize skip, csize;
 419   gsize toreuse, tocopy;
 420   guint8 *data;
 421
 422   g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
 423   g_return_val_if_fail (size > 0, NULL);
 424
 425   /* we don't have enough data, return NULL. This is unlikely
 426    * as one usually does an _available() first instead of peeking a
 427    * random size. */
 428   if (G_UNLIKELY (size > adapter->size))
 429     return NULL;
 430
 431   /* we have enough assembled data, return it */
 432   if (adapter->assembled_len >= size)
 433     return adapter->assembled_data;
 434
 435   do {
 436     cur = adapter->buflist->data;
 437     skip = adapter->skip;
 438
 439     csize = gst_buffer_get_size (cur);
 440     if (csize >= size + skip) {
 441       data = gst_buffer_map (cur, &csize, NULL, GST_MAP_READ);
 442       adapter->priv->cdata = data;
 443       adapter->priv->csize = csize;
 444       return data + skip;
 445     }
 446     /* We may be able to efficiently merge buffers in our pool to
 447      * gather a big enough chunk to return it from the head buffer directly */
 448   } while (gst_adapter_try_to_merge_up (adapter, size));
 449
 450   /* see how much data we can reuse from the assembled memory and how much
 451    * we need to copy */
 452   toreuse = adapter->assembled_len;
 453   tocopy = size - toreuse;
 454
 455   /* Gonna need to copy stuff out */
 456   if (G_UNLIKELY (adapter->assembled_size < size)) {
 457     adapter->assembled_size = (size / DEFAULT_SIZE + 1) * DEFAULT_SIZE;
 458     GST_DEBUG_OBJECT (adapter, "resizing internal buffer to %" G_GSIZE_FORMAT,
 459         adapter->assembled_size);
 460     if (toreuse == 0) {
 461       GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "alloc new buffer");
 462       /* no g_realloc to avoid a memcpy that is not desired here since we are
 463        * not going to reuse any data here */
 464       g_free (adapter->assembled_data);
 465       adapter->assembled_data = g_malloc (adapter->assembled_size);
 466     } else {
 467       /* we are going to reuse all data, realloc then */
 468       GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "reusing %" G_GSIZE_FORMAT " bytes",
 469           toreuse);
 470       adapter->assembled_data =
 471           g_realloc (adapter->assembled_data, adapter->assembled_size);
 472     }
 473   }
 474   GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy remaining %" G_GSIZE_FORMAT
 475       " bytes from adapter", tocopy);
 476   data = adapter->assembled_data;
 477   copy_into_unchecked (adapter, data + toreuse, skip + toreuse, tocopy);
 478   adapter->assembled_len = size;
 479
 480   return adapter->assembled_data;
 481 }
 482
 483 /**
 484  * gst_adapter_unmap:
 485  * @adapter: a #GstAdapter
 486  *
 487  * Releases the memory obtained with the last gst_adapter_map().
 488  */
 489 void
 490 gst_adapter_unmap (GstAdapter * adapter)
 491 {
 492   g_return_if_fail (GST_IS_ADAPTER (adapter));
 493
 494   if (adapter->priv->cdata) {
 495     GstBuffer *cur = adapter->buflist->data;
 496     gst_buffer_unmap (cur, adapter->priv->cdata, adapter->priv->csize);
 497     adapter->priv->cdata = NULL;
 498   }
 499 }
 500
 501 /**
 502  * gst_adapter_copy:
 503  * @adapter: a #GstAdapter
 504  * @dest: (out caller-allocates) (array length=size): the memory to copy into
 505  * @offset: the bytes offset in the adapter to start from
 506  * @size: the number of bytes to copy
 507  *
 508  * Copies @size bytes of data starting at @offset out of the buffers
 509  * contained in @GstAdapter into an array @dest provided by the caller.
 510  *
 511  * The array @dest should be large enough to contain @size bytes.
 512  * The user should check that the adapter has (@offset + @size) bytes
 513  * available before calling this function.
 514  *
 515  * Since: 0.10.12
 516  */
 517 void
 518 gst_adapter_copy (GstAdapter * adapter, gpointer dest, gsize offset, gsize size)
 519 {
 520   g_return_if_fail (GST_IS_ADAPTER (adapter));
 521   g_return_if_fail (size > 0);
 522   g_return_if_fail (offset + size <= adapter->size);
 523
 524   copy_into_unchecked (adapter, dest, offset + adapter->skip, size);
 525 }
 526
 527 /**
 528  * gst_adapter_flush:
 529  * @adapter: a #GstAdapter
 530  * @flush: the number of bytes to flush
 531  *
 532  * Flushes the first @flush bytes in the @adapter. The caller must ensure that
 533  * at least this many bytes are available.
 534  *
 535  * See also: gst_adapter_map(), gst_adapter_unmap()
 536  */
 537 static void
 538 gst_adapter_flush_unchecked (GstAdapter * adapter, gsize flush)
 539 {
 540   GstBuffer *cur;
 541   gsize size;
 542   GstAdapterPrivate *priv;
 543   GSList *g;
 544
 545   GST_LOG_OBJECT (adapter, "flushing %" G_GSIZE_FORMAT " bytes", flush);
 546
 547   priv = adapter->priv;
 548
 549   /* clear state */
 550   adapter->size -= flush;
 551   adapter->assembled_len = 0;
 552
 553   /* take skip into account */
 554   flush += adapter->skip;
 555   /* distance is always at least the amount of skipped bytes */
 556   priv->pts_distance -= adapter->skip;
 557   priv->dts_distance -= adapter->skip;
 558
 559   g = adapter->buflist;
 560   cur = g->data;
 561   size = gst_buffer_get_size (cur);
 562   while (flush >= size) {
 563     /* can skip whole buffer */
 564     GST_LOG_OBJECT (adapter, "flushing out head buffer");
 565     priv->pts_distance += size;
 566     priv->dts_distance += size;
 567     flush -= size;
 568
 569     gst_buffer_unref (cur);
 570     g = g_slist_delete_link (g, g);
 571
 572     if (G_UNLIKELY (g == NULL)) {
 573       GST_LOG_OBJECT (adapter, "adapter empty now");
 574       adapter->buflist_end = NULL;
 575       break;
 576     }
 577     /* there is a new head buffer, update the timestamps */
 578     cur = g->data;
 579     update_timestamps (adapter, cur);
 580     size = gst_buffer_get_size (cur);
 581   }
 582   adapter->buflist = g;
 583   /* account for the remaining bytes */
 584   adapter->skip = flush;
 585   adapter->priv->pts_distance += flush;
 586   adapter->priv->dts_distance += flush;
 587   /* invalidate scan position */
 588   priv->scan_offset = 0;
 589   priv->scan_entry = NULL;
 590 }
 591
 592 void
 593 gst_adapter_flush (GstAdapter * adapter, gsize flush)
 594 {
 595   g_return_if_fail (GST_IS_ADAPTER (adapter));
 596   g_return_if_fail (flush <= adapter->size);
 597
 598   /* flushing out 0 bytes will do nothing */
 599   if (G_UNLIKELY (flush == 0))
 600     return;
 601
 602   gst_adapter_flush_unchecked (adapter, flush);
 603 }
 604
 605 /* internal function, nbytes should be flushed after calling this function */
 606 static guint8 *
 607 gst_adapter_take_internal (GstAdapter * adapter, gsize nbytes)
 608 {
 609   guint8 *data;
 610   gsize toreuse, tocopy;
 611
 612   /* see how much data we can reuse from the assembled memory and how much
 613    * we need to copy */
 614   toreuse = MIN (nbytes, adapter->assembled_len);
 615   tocopy = nbytes - toreuse;
 616
 617   /* find memory to return */
 618   if (adapter->assembled_size >= nbytes && toreuse > 0) {
 619     /* we reuse already allocated memory but only when we're going to reuse
 620      * something from it because else we are worse than the malloc and copy
 621      * case below */
 622     GST_LOG_OBJECT (adapter, "reusing %" G_GSIZE_FORMAT " bytes of assembled"
 623         " data", toreuse);
 624     /* we have enough free space in the assembled array */
 625     data = adapter->assembled_data;
 626     /* flush after this function should set the assembled_size to 0 */
 627     adapter->assembled_data = g_malloc (adapter->assembled_size);
 628   } else {
 629     GST_LOG_OBJECT (adapter, "allocating %" G_GSIZE_FORMAT " bytes", nbytes);
 630     /* not enough bytes in the assembled array, just allocate new space */
 631     data = g_malloc (nbytes);
 632     /* reuse what we can from the already assembled data */
 633     if (toreuse) {
 634       GST_LOG_OBJECT (adapter, "reusing %" G_GSIZE_FORMAT " bytes", toreuse);
 635       memcpy (data, adapter->assembled_data, toreuse);
 636     }
 637   }
 638   if (tocopy) {
 639     /* copy the remaining data */
 640     copy_into_unchecked (adapter, toreuse + data, toreuse + adapter->skip,
 641         tocopy);
 642   }
 643   return data;
 644 }
 645
 646 /**
 647  * gst_adapter_take:
 648  * @adapter: a #GstAdapter
 649  * @nbytes: the number of bytes to take
 650  *
 651  * Returns a freshly allocated buffer containing the first @nbytes bytes of the
 652  * @adapter. The returned bytes will be flushed from the adapter.
 653  *
 654  * Caller owns returned value. g_free after usage.
 655  *
 656  * Free-function: g_free
 657  *
 658  * Returns: (transfer full) (array length=nbytes): oven-fresh hot data, or
 659  *     #NULL if @nbytes bytes are not available
 660  */
 661 gpointer
 662 gst_adapter_take (GstAdapter * adapter, gsize nbytes)
 663 {
 664   gpointer data;
 665
 666   g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
 667   g_return_val_if_fail (nbytes > 0, NULL);
 668
 669   /* we don't have enough data, return NULL. This is unlikely
 670    * as one usually does an _available() first instead of peeking a
 671    * random size. */
 672   if (G_UNLIKELY (nbytes > adapter->size))
 673     return NULL;
 674
 675   data = gst_adapter_take_internal (adapter, nbytes);
 676
 677   gst_adapter_flush_unchecked (adapter, nbytes);
 678
 679   return data;
 680 }
 681
 682 /**
 683  * gst_adapter_take_buffer:
 684  * @adapter: a #GstAdapter
 685  * @nbytes: the number of bytes to take
 686  *
 687  * Returns a #GstBuffer containing the first @nbytes bytes of the
 688  * @adapter. The returned bytes will be flushed from the adapter.
 689  * This function is potentially more performant than gst_adapter_take()
 690  * since it can reuse the memory in pushed buffers by subbuffering
 691  * or merging.
 692  *
 693  * Caller owns returned value. gst_buffer_unref() after usage.
 694  *
 695  * Free-function: gst_buffer_unref
 696  *
 697  * Returns: (transfer full): a #GstBuffer containing the first @nbytes of
 698  *     the adapter, or #NULL if @nbytes bytes are not available
 699  *
 700  * Since: 0.10.6
 701  */
 702 GstBuffer *
 703 gst_adapter_take_buffer (GstAdapter * adapter, gsize nbytes)
 704 {
 705   GstBuffer *buffer;
 706   GstBuffer *cur;
 707   gsize hsize, skip;
 708   guint8 *data;
 709
 710   g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
 711   g_return_val_if_fail (nbytes > 0, NULL);
 712
 713   GST_LOG_OBJECT (adapter, "taking buffer of %" G_GSIZE_FORMAT " bytes",
 714       nbytes);
 715
 716   /* we don't have enough data, return NULL. This is unlikely
 717    * as one usually does an _available() first instead of grabbing a
 718    * random size. */
 719   if (G_UNLIKELY (nbytes > adapter->size))
 720     return NULL;
 721
 722   cur = adapter->buflist->data;
 723   skip = adapter->skip;
 724   hsize = gst_buffer_get_size (cur);
 725
 726   /* our head buffer has enough data left, return it */
 727   if (skip == 0 && hsize == nbytes) {
 728     GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
 729         " as head buffer", nbytes);
 730     buffer = gst_buffer_ref (cur);
 731     goto done;
 732   } else if (hsize >= nbytes + skip) {
 733     GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
 734         " via region copy", nbytes);
 735     buffer = gst_buffer_copy_region (cur, GST_BUFFER_COPY_ALL, skip, nbytes);
 736     goto done;
 737   }
 738
 739   if (gst_adapter_try_to_merge_up (adapter, nbytes)) {
 740     /* Merged something, let's try again for sub-buffering */
 741     cur = adapter->buflist->data;
 742     if (gst_buffer_get_size (cur) >= nbytes + skip) {
 743       GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
 744           " via sub-buffer", nbytes);
 745       buffer = gst_buffer_copy_region (cur, GST_BUFFER_COPY_ALL, skip, nbytes);
 746       goto done;
 747     }
 748   }
 749
 750   data = gst_adapter_take_internal (adapter, nbytes);
 751
 752   buffer = gst_buffer_new ();
 753   gst_buffer_take_memory (buffer, -1,
 754       gst_memory_new_wrapped (0, data, g_free, nbytes, 0, nbytes));
 755
 756 done:
 757   gst_adapter_flush_unchecked (adapter, nbytes);
 758
 759   return buffer;
 760 }
 761
 762 /**
 763  * gst_adapter_take_list:
 764  * @adapter: a #GstAdapter
 765  * @nbytes: the number of bytes to take
 766  *
 767  * Returns a #GList of buffers containing the first @nbytes bytes of the
 768  * @adapter. The returned bytes will be flushed from the adapter.
 769  * When the caller can deal with individual buffers, this function is more
 770  * performant because no memory should be copied.
 771  *
 772  * Caller owns returned list and contained buffers. gst_buffer_unref() each
 773  * buffer in the list before freeing the list after usage.
 774  *
 775  * Returns: (element-type Gst.Buffer) (transfer full): a #GList of buffers
 776  *     containing the first @nbytes of the adapter, or #NULL if @nbytes bytes
 777  *     are not available
 778  *
 779  * Since: 0.10.31
 780  */
 781 GList *
 782 gst_adapter_take_list (GstAdapter * adapter, gsize nbytes)
 783 {
 784   GQueue queue = G_QUEUE_INIT;
 785   GstBuffer *cur;
 786   gsize hsize, skip;
 787
 788   g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
 789   g_return_val_if_fail (nbytes <= adapter->size, NULL);
 790
 791   GST_LOG_OBJECT (adapter, "taking %" G_GSIZE_FORMAT " bytes", nbytes);
 792
 793   while (nbytes > 0) {
 794     cur = adapter->buflist->data;
 795     skip = adapter->skip;
 796     hsize = MIN (nbytes, gst_buffer_get_size (cur) - skip);
 797
 798     cur = gst_adapter_take_buffer (adapter, hsize);
 799
 800     g_queue_push_tail (&queue, cur);
 801
 802     nbytes -= hsize;
 803   }
 804   return queue.head;
 805 }
 806
 807 /**
 808  * gst_adapter_available:
 809  * @adapter: a #GstAdapter
 810  *
 811  * Gets the maximum amount of bytes available, that is it returns the maximum
 812  * value that can be supplied to gst_adapter_map() without that function
 813  * returning NULL.
 814  *
 815  * Returns: number of bytes available in @adapter
 816  */
 817 gsize
 818 gst_adapter_available (GstAdapter * adapter)
 819 {
 820   g_return_val_if_fail (GST_IS_ADAPTER (adapter), 0);
 821
 822   return adapter->size;
 823 }
 824
 825 /**
 826  * gst_adapter_available_fast:
 827  * @adapter: a #GstAdapter
 828  *
 829  * Gets the maximum number of bytes that are immediately available without
 830  * requiring any expensive operations (like copying the data into a
 831  * temporary buffer).
 832  *
 833  * Returns: number of bytes that are available in @adapter without expensive
 834  * operations
 835  */
 836 gsize
 837 gst_adapter_available_fast (GstAdapter * adapter)
 838 {
 839   GstBuffer *cur;
 840   gsize size;
 841   GSList *g;
 842
 843   g_return_val_if_fail (GST_IS_ADAPTER (adapter), 0);
 844
 845   /* no data */
 846   if (adapter->size == 0)
 847     return 0;
 848
 849   /* some stuff we already assembled */
 850   if (adapter->assembled_len)
 851     return adapter->assembled_len;
 852
 853   /* take the first non-zero buffer */
 854   g = adapter->buflist;
 855   while (TRUE) {
 856     cur = g->data;
 857     size = gst_buffer_get_size (cur);
 858     if (size != 0)
 859       break;
 860     g = g_slist_next (g);
 861   }
 862
 863   /* we can quickly get the (remaining) data of the first buffer */
 864   return size - adapter->skip;
 865 }
 866
 867 /**
 868  * gst_adapter_prev_pts:
 869  * @adapter: a #GstAdapter
 870  * @distance: (out) (allow-none): pointer to location for distance, or NULL
 871  *
 872  * Get the pts that was before the current byte in the adapter. When
 873  * @distance is given, the amount of bytes between the pts and the current
 874  * position is returned.
 875  *
 876  * The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when
 877  * the adapter is first created or when it is cleared. This also means that before
 878  * the first byte with a pts is removed from the adapter, the pts
 879  * and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
 880  *
 881  * Returns: The previously seen pts.
 882  */
 883 GstClockTime
 884 gst_adapter_prev_pts (GstAdapter * adapter, guint64 * distance)
 885 {
 886   g_return_val_if_fail (GST_IS_ADAPTER (adapter), GST_CLOCK_TIME_NONE);
 887
 888   if (distance)
 889     *distance = adapter->priv->pts_distance;
 890
 891   return adapter->priv->pts;
 892 }
 893
 894 /**
 895  * gst_adapter_prev_dts:
 896  * @adapter: a #GstAdapter
 897  * @distance: (out) (allow-none): pointer to location for distance, or NULL
 898  *
 899  * Get the dts that was before the current byte in the adapter. When
 900  * @distance is given, the amount of bytes between the dts and the current
 901  * position is returned.
 902  *
 903  * The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when
 904  * the adapter is first created or when it is cleared. This also means that before
 905  * the first byte with a dts is removed from the adapter, the dts
 906  * and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
 907  *
 908  * Returns: The previously seen dts.
 909  */
 910 GstClockTime
 911 gst_adapter_prev_dts (GstAdapter * adapter, guint64 * distance)
 912 {
 913   g_return_val_if_fail (GST_IS_ADAPTER (adapter), GST_CLOCK_TIME_NONE);
 914
 915   if (distance)
 916     *distance = adapter->priv->dts_distance;
 917
 918   return adapter->priv->dts;
 919 }
 920
 921 /**
 922  * gst_adapter_masked_scan_uint32_peek:
 923  * @adapter: a #GstAdapter
 924  * @mask: mask to apply to data before matching against @pattern
 925  * @pattern: pattern to match (after mask is applied)
 926  * @offset: offset into the adapter data from which to start scanning, returns
 927  *          the last scanned position.
 928  * @size: number of bytes to scan from offset
 929  * @value: pointer to uint32 to return matching data
 930  *
 931  * Scan for pattern @pattern with applied mask @mask in the adapter data,
 932  * starting from offset @offset.  If a match is found, the value that matched
 933  * is returned through @value, otherwise @value is left untouched.
 934  *
 935  * The bytes in @pattern and @mask are interpreted left-to-right, regardless
 936  * of endianness.  All four bytes of the pattern must be present in the
 937  * adapter for it to match, even if the first or last bytes are masked out.
 938  *
 939  * It is an error to call this function without making sure that there is
 940  * enough data (offset+size bytes) in the adapter.
 941  *
 942  * Returns: offset of the first match, or -1 if no match was found.
 943  *
 944  * Since: 0.10.30
 945  */
 946 gsize
 947 gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask,
 948     guint32 pattern, gsize offset, gsize size, guint32 * value)
 949 {
 950   GSList *g;
 951   gsize skip, bsize, osize, i;
 952   guint32 state;
 953   guint8 *bdata, *odata;
 954   GstBuffer *buf;
 955
 956   g_return_val_if_fail (size > 0, -1);
 957   g_return_val_if_fail (offset + size <= adapter->size, -1);
 958   g_return_val_if_fail (((~mask) & pattern) == 0, -1);
 959
 960   /* we can't find the pattern with less than 4 bytes */
 961   if (G_UNLIKELY (size < 4))
 962     return -1;
 963
 964   skip = offset + adapter->skip;
 965
 966   /* first step, do skipping and position on the first buffer */
 967   /* optimistically assume scanning continues sequentially */
 968   if (adapter->priv->scan_entry && (adapter->priv->scan_offset <= skip)) {
 969     g = adapter->priv->scan_entry;
 970     skip -= adapter->priv->scan_offset;
 971   } else {
 972     g = adapter->buflist;
 973     adapter->priv->scan_offset = 0;
 974     adapter->priv->scan_entry = NULL;
 975   }
 976   buf = g->data;
 977   bsize = gst_buffer_get_size (buf);
 978   while (G_UNLIKELY (skip >= bsize)) {
 979     skip -= bsize;
 980     g = g_slist_next (g);
 981     adapter->priv->scan_offset += bsize;
 982     adapter->priv->scan_entry = g;
 983     buf = g->data;
 984     bsize = gst_buffer_get_size (buf);
 985   }
 986   /* get the data now */
 987   odata = gst_buffer_map (buf, &osize, NULL, GST_MAP_READ);
 988
 989   bdata = odata + skip;
 990   bsize = osize - skip;
 991   skip = 0;
 992
 993   /* set the state to something that does not match */
 994   state = ~pattern;
 995
 996   /* now find data */
 997   do {
 998     bsize = MIN (bsize, size);
 999     for (i = 0; i < bsize; i++) {
1000       state = ((state << 8) | bdata[i]);
1001       if (G_UNLIKELY ((state & mask) == pattern)) {
1002         /* we have a match but we need to have skipped at
1003          * least 4 bytes to fill the state. */
1004         if (G_LIKELY (skip + i >= 3)) {
1005           if (G_LIKELY (value))
1006             *value = state;
1007           gst_buffer_unmap (buf, odata, osize);
1008           return offset + skip + i - 3;
1009         }
1010       }
1011     }
1012     size -= bsize;
1013     if (size == 0)
1014       break;
1015
1016     /* nothing found yet, go to next buffer */
1017     skip += bsize;
1018     g = g_slist_next (g);
1019     adapter->priv->scan_offset += osize;
1020     adapter->priv->scan_entry = g;
1021     gst_buffer_unmap (buf, odata, osize);
1022     buf = g->data;
1023
1024     odata = gst_buffer_map (buf, &osize, NULL, GST_MAP_READ);
1025     bsize = osize;
1026     bdata = odata;
1027   } while (TRUE);
1028
1029   gst_buffer_unmap (buf, odata, osize);
1030
1031   /* nothing found */
1032   return -1;
1033 }
1034
1035 /**
1036  * gst_adapter_masked_scan_uint32:
1037  * @adapter: a #GstAdapter
1038  * @mask: mask to apply to data before matching against @pattern
1039  * @pattern: pattern to match (after mask is applied)
1040  * @offset: offset into the adapter data from which to start scanning, returns
1041  *          the last scanned position.
1042  * @size: number of bytes to scan from offset
1043  *
1044  * Scan for pattern @pattern with applied mask @mask in the adapter data,
1045  * starting from offset @offset.
1046  *
1047  * The bytes in @pattern and @mask are interpreted left-to-right, regardless
1048  * of endianness.  All four bytes of the pattern must be present in the
1049  * adapter for it to match, even if the first or last bytes are masked out.
1050  *
1051  * It is an error to call this function without making sure that there is
1052  * enough data (offset+size bytes) in the adapter.
1053  *
1054  * This function calls gst_adapter_masked_scan_uint32_peek() passing NULL
1055  * for value.
1056  *
1057  * Returns: offset of the first match, or -1 if no match was found.
1058  *
1059  * Example:
1060  * <programlisting>
1061  * // Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff
1062  *
1063  * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256);
1064  * // -> returns 0
1065  * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255);
1066  * // -> returns -1
1067  * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255);
1068  * // -> returns 1
1069  * gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256);
1070  * // -> returns -1
1071  * gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256);
1072  * // -> returns 0
1073  * gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256);
1074  * // -> returns 2
1075  * gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4);
1076  * // -> returns -1
1077  * </programlisting>
1078  *
1079  * Since: 0.10.24
1080  */
1081 gsize
1082 gst_adapter_masked_scan_uint32 (GstAdapter * adapter, guint32 mask,
1083     guint32 pattern, gsize offset, gsize size)
1084 {
1085   return gst_adapter_masked_scan_uint32_peek (adapter, mask, pattern, offset,
1086       size, NULL);
1087 }