2 * Copyright (C) 2004 Benjamin Otte <otte@gnome.org>
3 * 2005 Wim Taymans <wim@fluendo.com>
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.
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.
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.
23 * @short_description: adapts incoming data on a sink pad into chunks of N bytes
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.
31 * An adapter is created with gst_adapter_new(). It can be freed again with
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().
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.
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:
47 * static GstFlowReturn
48 * sink_pad_chain (GstPad *pad, GstBuffer *buffer)
51 * GstAdapter *adapter;
52 * GstFlowReturn ret = GST_FLOW_OK;
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;
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);
69 * gst_object_unref (this);
74 * For another example, a simple element inside GStreamer that uses GstAdapter
75 * is the libvisual element.
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.
82 * Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might
83 * need to clear the adapter after a discontinuity.
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.
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.
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.
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.
112 * Last reviewed on 2009-05-13 (0.10.24).
115 #include <gst/gst_private.h>
116 #include "gstadapter.h"
119 /* default size for the assembled data buffer */
120 #define DEFAULT_SIZE 4096
122 static void gst_adapter_flush_unchecked (GstAdapter * adapter, gsize flush);
124 GST_DEBUG_CATEGORY_STATIC (gst_adapter_debug);
125 #define GST_CAT_DEFAULT gst_adapter_debug
127 #define GST_ADAPTER_GET_PRIVATE(obj) \
128 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_ADAPTER, GstAdapterPrivate))
130 struct _GstAdapterPrivate
133 guint64 pts_distance;
135 guint64 dts_distance;
144 GST_DEBUG_CATEGORY_INIT (gst_adapter_debug, "adapter", 0, "object to splice and merge buffers to desired size")
145 #define gst_adapter_parent_class parent_class
146 G_DEFINE_TYPE_WITH_CODE (GstAdapter, gst_adapter, G_TYPE_OBJECT, _do_init);
148 static void gst_adapter_dispose (GObject * object);
149 static void gst_adapter_finalize (GObject * object);
152 gst_adapter_class_init (GstAdapterClass * klass)
154 GObjectClass *object = G_OBJECT_CLASS (klass);
156 g_type_class_add_private (klass, sizeof (GstAdapterPrivate));
158 object->dispose = gst_adapter_dispose;
159 object->finalize = gst_adapter_finalize;
163 gst_adapter_init (GstAdapter * adapter)
165 adapter->priv = GST_ADAPTER_GET_PRIVATE (adapter);
166 adapter->assembled_data = g_malloc (DEFAULT_SIZE);
167 adapter->assembled_size = DEFAULT_SIZE;
168 adapter->priv->pts = GST_CLOCK_TIME_NONE;
169 adapter->priv->pts_distance = 0;
170 adapter->priv->dts = GST_CLOCK_TIME_NONE;
171 adapter->priv->dts_distance = 0;
175 gst_adapter_dispose (GObject * object)
177 GstAdapter *adapter = GST_ADAPTER (object);
179 gst_adapter_clear (adapter);
181 GST_CALL_PARENT (G_OBJECT_CLASS, dispose, (object));
185 gst_adapter_finalize (GObject * object)
187 GstAdapter *adapter = GST_ADAPTER (object);
189 g_free (adapter->assembled_data);
191 GST_CALL_PARENT (G_OBJECT_CLASS, finalize, (object));
197 * Creates a new #GstAdapter. Free with g_object_unref().
199 * Returns: (transfer full): a new #GstAdapter
202 gst_adapter_new (void)
204 return g_object_newv (GST_TYPE_ADAPTER, 0, NULL);
209 * @adapter: a #GstAdapter
211 * Removes all buffers from @adapter.
214 gst_adapter_clear (GstAdapter * adapter)
216 GstAdapterPrivate *priv;
218 g_return_if_fail (GST_IS_ADAPTER (adapter));
220 priv = adapter->priv;
222 if (priv->info.memory)
223 gst_adapter_unmap (adapter);
225 g_slist_foreach (adapter->buflist, (GFunc) gst_mini_object_unref, NULL);
226 g_slist_free (adapter->buflist);
227 adapter->buflist = NULL;
228 adapter->buflist_end = NULL;
231 adapter->assembled_len = 0;
232 priv->pts = GST_CLOCK_TIME_NONE;
233 priv->pts_distance = 0;
234 priv->dts = GST_CLOCK_TIME_NONE;
235 priv->dts_distance = 0;
236 priv->scan_offset = 0;
237 priv->scan_entry = NULL;
241 update_timestamps (GstAdapter * adapter, GstBuffer * buf)
243 GstClockTime pts, dts;
245 pts = GST_BUFFER_PTS (buf);
246 if (GST_CLOCK_TIME_IS_VALID (pts)) {
247 GST_LOG_OBJECT (adapter, "new pts %" GST_TIME_FORMAT, GST_TIME_ARGS (pts));
248 adapter->priv->pts = pts;
249 adapter->priv->pts_distance = 0;
251 dts = GST_BUFFER_DTS (buf);
252 if (GST_CLOCK_TIME_IS_VALID (dts)) {
253 GST_LOG_OBJECT (adapter, "new dts %" GST_TIME_FORMAT, GST_TIME_ARGS (dts));
254 adapter->priv->dts = dts;
255 adapter->priv->dts_distance = 0;
259 /* copy data into @dest, skipping @skip bytes from the head buffers */
261 copy_into_unchecked (GstAdapter * adapter, guint8 * dest, gsize skip,
268 /* first step, do skipping */
269 /* we might well be copying where we were scanning */
270 if (adapter->priv->scan_entry && (adapter->priv->scan_offset <= skip)) {
271 g = adapter->priv->scan_entry;
272 skip -= adapter->priv->scan_offset;
274 g = adapter->buflist;
277 bsize = gst_buffer_get_size (buf);
278 while (G_UNLIKELY (skip >= bsize)) {
280 g = g_slist_next (g);
282 bsize = gst_buffer_get_size (buf);
284 /* copy partial buffer */
285 csize = MIN (bsize - skip, size);
286 GST_DEBUG ("bsize %" G_GSIZE_FORMAT ", skip %" G_GSIZE_FORMAT ", csize %"
287 G_GSIZE_FORMAT, bsize, skip, csize);
288 GST_CAT_LOG_OBJECT (GST_CAT_PERFORMANCE, adapter, "extract %" G_GSIZE_FORMAT
290 gst_buffer_extract (buf, skip, dest, csize);
294 /* second step, copy remainder */
296 g = g_slist_next (g);
298 bsize = gst_buffer_get_size (buf);
299 if (G_LIKELY (bsize > 0)) {
300 csize = MIN (bsize, size);
301 GST_CAT_LOG_OBJECT (GST_CAT_PERFORMANCE, adapter,
302 "extract %" G_GSIZE_FORMAT " bytes", csize);
303 gst_buffer_extract (buf, 0, dest, csize);
312 * @adapter: a #GstAdapter
313 * @buf: (transfer full): a #GstBuffer to add to queue in the adapter
315 * Adds the data from @buf to the data stored inside @adapter and takes
316 * ownership of the buffer.
319 gst_adapter_push (GstAdapter * adapter, GstBuffer * buf)
323 g_return_if_fail (GST_IS_ADAPTER (adapter));
324 g_return_if_fail (GST_IS_BUFFER (buf));
326 size = gst_buffer_get_size (buf);
327 adapter->size += size;
329 /* Note: merging buffers at this point is premature. */
330 if (G_UNLIKELY (adapter->buflist == NULL)) {
331 GST_LOG_OBJECT (adapter, "pushing %p first %" G_GSIZE_FORMAT " bytes",
333 adapter->buflist = adapter->buflist_end = g_slist_append (NULL, buf);
334 update_timestamps (adapter, buf);
336 /* Otherwise append to the end, and advance our end pointer */
337 GST_LOG_OBJECT (adapter, "pushing %p %" G_GSIZE_FORMAT " bytes at end, "
338 "size now %" G_GSIZE_FORMAT, buf, size, adapter->size);
339 adapter->buflist_end = g_slist_append (adapter->buflist_end, buf);
340 adapter->buflist_end = g_slist_next (adapter->buflist_end);
344 /* Internal method only. Tries to merge buffers at the head of the queue
345 * to form a single larger buffer of size 'size'. Only merges buffers that
346 * where 'gst_buffer_is_span_fast' returns TRUE.
348 * Returns TRUE if it managed to merge anything.
351 gst_adapter_try_to_merge_up (GstAdapter * adapter, gsize size)
353 GstBuffer *cur, *head;
355 gboolean ret = FALSE;
358 g = adapter->buflist;
363 g = g_slist_next (g);
365 /* How large do we want our head buffer? The requested size, plus whatever's
366 * been skipped already */
367 size += adapter->skip;
368 hsize = gst_buffer_get_size (head);
370 while (g != NULL && hsize < size) {
372 if (!gst_buffer_is_span_fast (head, cur))
375 /* Merge the head buffer and the next in line */
376 GST_LOG_OBJECT (adapter, "Merging buffers of size %" G_GSIZE_FORMAT " & %"
377 G_GSIZE_FORMAT " in search of target %" G_GSIZE_FORMAT,
378 hsize, gst_buffer_get_size (cur), size);
380 head = gst_buffer_join (head, cur);
381 hsize = gst_buffer_get_size (head);
384 /* Delete the front list item, and store our new buffer in the 2nd list
386 adapter->buflist = g_slist_delete_link (adapter->buflist, adapter->buflist);
389 /* invalidate scan position */
390 adapter->priv->scan_offset = 0;
391 adapter->priv->scan_entry = NULL;
393 g = g_slist_next (g);
401 * @adapter: a #GstAdapter
402 * @size: the number of bytes to map/peek
404 * Gets the first @size bytes stored in the @adapter. The returned pointer is
405 * valid until the next function is called on the adapter.
407 * Note that setting the returned pointer as the data of a #GstBuffer is
408 * incorrect for general-purpose plugins. The reason is that if a downstream
409 * element stores the buffer so that it has access to it outside of the bounds
410 * of its chain function, the buffer will have an invalid data pointer after
411 * your element flushes the bytes. In that case you should use
412 * gst_adapter_take(), which returns a freshly-allocated buffer that you can set
413 * as #GstBuffer malloc_data or the potentially more performant
414 * gst_adapter_take_buffer().
416 * Returns #NULL if @size bytes are not available.
418 * Returns: (transfer none) (array length=size): a pointer to the first
419 * @size bytes of data, or NULL
422 gst_adapter_map (GstAdapter * adapter, gsize size)
424 GstAdapterPrivate *priv;
427 gsize toreuse, tocopy;
430 g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
431 g_return_val_if_fail (size > 0, NULL);
433 priv = adapter->priv;
435 if (priv->info.memory)
436 gst_adapter_unmap (adapter);
438 /* we don't have enough data, return NULL. This is unlikely
439 * as one usually does an _available() first instead of peeking a
441 if (G_UNLIKELY (size > adapter->size))
444 /* we have enough assembled data, return it */
445 if (adapter->assembled_len >= size)
446 return adapter->assembled_data;
449 cur = adapter->buflist->data;
450 skip = adapter->skip;
452 csize = gst_buffer_get_size (cur);
453 if (csize >= size + skip) {
454 if (!gst_buffer_map (cur, &priv->info, GST_MAP_READ))
457 return (guint8 *) priv->info.data + skip;
459 /* We may be able to efficiently merge buffers in our pool to
460 * gather a big enough chunk to return it from the head buffer directly */
461 } while (gst_adapter_try_to_merge_up (adapter, size));
463 /* see how much data we can reuse from the assembled memory and how much
465 toreuse = adapter->assembled_len;
466 tocopy = size - toreuse;
468 /* Gonna need to copy stuff out */
469 if (G_UNLIKELY (adapter->assembled_size < size)) {
470 adapter->assembled_size = (size / DEFAULT_SIZE + 1) * DEFAULT_SIZE;
471 GST_DEBUG_OBJECT (adapter, "resizing internal buffer to %" G_GSIZE_FORMAT,
472 adapter->assembled_size);
474 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "alloc new buffer");
475 /* no g_realloc to avoid a memcpy that is not desired here since we are
476 * not going to reuse any data here */
477 g_free (adapter->assembled_data);
478 adapter->assembled_data = g_malloc (adapter->assembled_size);
480 /* we are going to reuse all data, realloc then */
481 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "reusing %" G_GSIZE_FORMAT " bytes",
483 adapter->assembled_data =
484 g_realloc (adapter->assembled_data, adapter->assembled_size);
487 GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy remaining %" G_GSIZE_FORMAT
488 " bytes from adapter", tocopy);
489 data = adapter->assembled_data;
490 copy_into_unchecked (adapter, data + toreuse, skip + toreuse, tocopy);
491 adapter->assembled_len = size;
493 return adapter->assembled_data;
498 * @adapter: a #GstAdapter
500 * Releases the memory obtained with the last gst_adapter_map().
503 gst_adapter_unmap (GstAdapter * adapter)
505 GstAdapterPrivate *priv;
507 g_return_if_fail (GST_IS_ADAPTER (adapter));
509 priv = adapter->priv;
511 if (priv->info.memory) {
512 GstBuffer *cur = adapter->buflist->data;
513 GST_LOG_OBJECT (adapter, "unmap memory buffer %p", cur);
514 gst_buffer_unmap (cur, &priv->info);
515 priv->info.memory = NULL;
521 * @adapter: a #GstAdapter
522 * @dest: (out caller-allocates) (array length=size): the memory to copy into
523 * @offset: the bytes offset in the adapter to start from
524 * @size: the number of bytes to copy
526 * Copies @size bytes of data starting at @offset out of the buffers
527 * contained in @GstAdapter into an array @dest provided by the caller.
529 * The array @dest should be large enough to contain @size bytes.
530 * The user should check that the adapter has (@offset + @size) bytes
531 * available before calling this function.
536 gst_adapter_copy (GstAdapter * adapter, gpointer dest, gsize offset, gsize size)
538 g_return_if_fail (GST_IS_ADAPTER (adapter));
539 g_return_if_fail (size > 0);
540 g_return_if_fail (offset + size <= adapter->size);
542 copy_into_unchecked (adapter, dest, offset + adapter->skip, size);
547 * @adapter: a #GstAdapter
548 * @flush: the number of bytes to flush
550 * Flushes the first @flush bytes in the @adapter. The caller must ensure that
551 * at least this many bytes are available.
553 * See also: gst_adapter_map(), gst_adapter_unmap()
556 gst_adapter_flush_unchecked (GstAdapter * adapter, gsize flush)
560 GstAdapterPrivate *priv;
563 GST_LOG_OBJECT (adapter, "flushing %" G_GSIZE_FORMAT " bytes", flush);
565 priv = adapter->priv;
567 if (priv->info.memory)
568 gst_adapter_unmap (adapter);
571 adapter->size -= flush;
572 adapter->assembled_len = 0;
574 /* take skip into account */
575 flush += adapter->skip;
576 /* distance is always at least the amount of skipped bytes */
577 priv->pts_distance -= adapter->skip;
578 priv->dts_distance -= adapter->skip;
580 g = adapter->buflist;
582 size = gst_buffer_get_size (cur);
583 while (flush >= size) {
584 /* can skip whole buffer */
585 GST_LOG_OBJECT (adapter, "flushing out head buffer");
586 priv->pts_distance += size;
587 priv->dts_distance += size;
590 gst_buffer_unref (cur);
591 g = g_slist_delete_link (g, g);
593 if (G_UNLIKELY (g == NULL)) {
594 GST_LOG_OBJECT (adapter, "adapter empty now");
595 adapter->buflist_end = NULL;
598 /* there is a new head buffer, update the timestamps */
600 update_timestamps (adapter, cur);
601 size = gst_buffer_get_size (cur);
603 adapter->buflist = g;
604 /* account for the remaining bytes */
605 adapter->skip = flush;
606 adapter->priv->pts_distance += flush;
607 adapter->priv->dts_distance += flush;
608 /* invalidate scan position */
609 priv->scan_offset = 0;
610 priv->scan_entry = NULL;
614 gst_adapter_flush (GstAdapter * adapter, gsize flush)
616 g_return_if_fail (GST_IS_ADAPTER (adapter));
617 g_return_if_fail (flush <= adapter->size);
619 /* flushing out 0 bytes will do nothing */
620 if (G_UNLIKELY (flush == 0))
623 gst_adapter_flush_unchecked (adapter, flush);
626 /* internal function, nbytes should be flushed after calling this function */
628 gst_adapter_take_internal (GstAdapter * adapter, gsize nbytes)
631 gsize toreuse, tocopy;
633 /* see how much data we can reuse from the assembled memory and how much
635 toreuse = MIN (nbytes, adapter->assembled_len);
636 tocopy = nbytes - toreuse;
638 /* find memory to return */
639 if (adapter->assembled_size >= nbytes && toreuse > 0) {
640 /* we reuse already allocated memory but only when we're going to reuse
641 * something from it because else we are worse than the malloc and copy
643 GST_LOG_OBJECT (adapter, "reusing %" G_GSIZE_FORMAT " bytes of assembled"
645 /* we have enough free space in the assembled array */
646 data = adapter->assembled_data;
647 /* flush after this function should set the assembled_size to 0 */
648 adapter->assembled_data = g_malloc (adapter->assembled_size);
650 GST_LOG_OBJECT (adapter, "allocating %" G_GSIZE_FORMAT " bytes", nbytes);
651 /* not enough bytes in the assembled array, just allocate new space */
652 data = g_malloc (nbytes);
653 /* reuse what we can from the already assembled data */
655 GST_LOG_OBJECT (adapter, "reusing %" G_GSIZE_FORMAT " bytes", toreuse);
656 GST_CAT_LOG_OBJECT (GST_CAT_PERFORMANCE, adapter,
657 "memcpy %" G_GSIZE_FORMAT " bytes", toreuse);
658 memcpy (data, adapter->assembled_data, toreuse);
662 /* copy the remaining data */
663 copy_into_unchecked (adapter, toreuse + data, toreuse + adapter->skip,
671 * @adapter: a #GstAdapter
672 * @nbytes: the number of bytes to take
674 * Returns a freshly allocated buffer containing the first @nbytes bytes of the
675 * @adapter. The returned bytes will be flushed from the adapter.
677 * Caller owns returned value. g_free after usage.
679 * Free-function: g_free
681 * Returns: (transfer full) (array length=nbytes): oven-fresh hot data, or
682 * #NULL if @nbytes bytes are not available
685 gst_adapter_take (GstAdapter * adapter, gsize nbytes)
689 g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
690 g_return_val_if_fail (nbytes > 0, NULL);
692 /* we don't have enough data, return NULL. This is unlikely
693 * as one usually does an _available() first instead of peeking a
695 if (G_UNLIKELY (nbytes > adapter->size))
698 data = gst_adapter_take_internal (adapter, nbytes);
700 gst_adapter_flush_unchecked (adapter, nbytes);
706 * gst_adapter_take_buffer:
707 * @adapter: a #GstAdapter
708 * @nbytes: the number of bytes to take
710 * Returns a #GstBuffer containing the first @nbytes bytes of the
711 * @adapter. The returned bytes will be flushed from the adapter.
712 * This function is potentially more performant than gst_adapter_take()
713 * since it can reuse the memory in pushed buffers by subbuffering
716 * Caller owns returned value. gst_buffer_unref() after usage.
718 * Free-function: gst_buffer_unref
720 * Returns: (transfer full): a #GstBuffer containing the first @nbytes of
721 * the adapter, or #NULL if @nbytes bytes are not available
726 gst_adapter_take_buffer (GstAdapter * adapter, gsize nbytes)
733 g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
734 g_return_val_if_fail (nbytes > 0, NULL);
736 GST_LOG_OBJECT (adapter, "taking buffer of %" G_GSIZE_FORMAT " bytes",
739 /* we don't have enough data, return NULL. This is unlikely
740 * as one usually does an _available() first instead of grabbing a
742 if (G_UNLIKELY (nbytes > adapter->size))
745 cur = adapter->buflist->data;
746 skip = adapter->skip;
747 hsize = gst_buffer_get_size (cur);
749 /* our head buffer has enough data left, return it */
750 if (skip == 0 && hsize == nbytes) {
751 GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
752 " as head buffer", nbytes);
753 buffer = gst_buffer_ref (cur);
755 } else if (hsize >= nbytes + skip) {
756 GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
757 " via region copy", nbytes);
758 buffer = gst_buffer_copy_region (cur, GST_BUFFER_COPY_ALL, skip, nbytes);
762 if (gst_adapter_try_to_merge_up (adapter, nbytes)) {
763 /* Merged something, let's try again for sub-buffering */
764 cur = adapter->buflist->data;
765 if (gst_buffer_get_size (cur) >= nbytes + skip) {
766 GST_LOG_OBJECT (adapter, "providing buffer of %" G_GSIZE_FORMAT " bytes"
767 " via sub-buffer", nbytes);
768 buffer = gst_buffer_copy_region (cur, GST_BUFFER_COPY_ALL, skip, nbytes);
773 data = gst_adapter_take_internal (adapter, nbytes);
775 buffer = gst_buffer_new ();
776 gst_buffer_take_memory (buffer, -1,
777 gst_memory_new_wrapped (0, data, nbytes, 0, nbytes, data, g_free));
780 gst_adapter_flush_unchecked (adapter, nbytes);
786 * gst_adapter_take_list:
787 * @adapter: a #GstAdapter
788 * @nbytes: the number of bytes to take
790 * Returns a #GList of buffers containing the first @nbytes bytes of the
791 * @adapter. The returned bytes will be flushed from the adapter.
792 * When the caller can deal with individual buffers, this function is more
793 * performant because no memory should be copied.
795 * Caller owns returned list and contained buffers. gst_buffer_unref() each
796 * buffer in the list before freeing the list after usage.
798 * Returns: (element-type Gst.Buffer) (transfer full): a #GList of buffers
799 * containing the first @nbytes of the adapter, or #NULL if @nbytes bytes
805 gst_adapter_take_list (GstAdapter * adapter, gsize nbytes)
807 GQueue queue = G_QUEUE_INIT;
811 g_return_val_if_fail (GST_IS_ADAPTER (adapter), NULL);
812 g_return_val_if_fail (nbytes <= adapter->size, NULL);
814 GST_LOG_OBJECT (adapter, "taking %" G_GSIZE_FORMAT " bytes", nbytes);
817 cur = adapter->buflist->data;
818 skip = adapter->skip;
819 hsize = MIN (nbytes, gst_buffer_get_size (cur) - skip);
821 cur = gst_adapter_take_buffer (adapter, hsize);
823 g_queue_push_tail (&queue, cur);
831 * gst_adapter_available:
832 * @adapter: a #GstAdapter
834 * Gets the maximum amount of bytes available, that is it returns the maximum
835 * value that can be supplied to gst_adapter_map() without that function
838 * Returns: number of bytes available in @adapter
841 gst_adapter_available (GstAdapter * adapter)
843 g_return_val_if_fail (GST_IS_ADAPTER (adapter), 0);
845 return adapter->size;
849 * gst_adapter_available_fast:
850 * @adapter: a #GstAdapter
852 * Gets the maximum number of bytes that are immediately available without
853 * requiring any expensive operations (like copying the data into a
856 * Returns: number of bytes that are available in @adapter without expensive
860 gst_adapter_available_fast (GstAdapter * adapter)
866 g_return_val_if_fail (GST_IS_ADAPTER (adapter), 0);
869 if (adapter->size == 0)
872 /* some stuff we already assembled */
873 if (adapter->assembled_len)
874 return adapter->assembled_len;
876 /* take the first non-zero buffer */
877 g = adapter->buflist;
880 size = gst_buffer_get_size (cur);
883 g = g_slist_next (g);
886 /* we can quickly get the (remaining) data of the first buffer */
887 return size - adapter->skip;
891 * gst_adapter_prev_pts:
892 * @adapter: a #GstAdapter
893 * @distance: (out) (allow-none): pointer to location for distance, or NULL
895 * Get the pts that was before the current byte in the adapter. When
896 * @distance is given, the amount of bytes between the pts and the current
897 * position is returned.
899 * The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when
900 * the adapter is first created or when it is cleared. This also means that before
901 * the first byte with a pts is removed from the adapter, the pts
902 * and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
904 * Returns: The previously seen pts.
907 gst_adapter_prev_pts (GstAdapter * adapter, guint64 * distance)
909 g_return_val_if_fail (GST_IS_ADAPTER (adapter), GST_CLOCK_TIME_NONE);
912 *distance = adapter->priv->pts_distance;
914 return adapter->priv->pts;
918 * gst_adapter_prev_dts:
919 * @adapter: a #GstAdapter
920 * @distance: (out) (allow-none): pointer to location for distance, or NULL
922 * Get the dts that was before the current byte in the adapter. When
923 * @distance is given, the amount of bytes between the dts and the current
924 * position is returned.
926 * The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when
927 * the adapter is first created or when it is cleared. This also means that before
928 * the first byte with a dts is removed from the adapter, the dts
929 * and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
931 * Returns: The previously seen dts.
934 gst_adapter_prev_dts (GstAdapter * adapter, guint64 * distance)
936 g_return_val_if_fail (GST_IS_ADAPTER (adapter), GST_CLOCK_TIME_NONE);
939 *distance = adapter->priv->dts_distance;
941 return adapter->priv->dts;
945 * gst_adapter_masked_scan_uint32_peek:
946 * @adapter: a #GstAdapter
947 * @mask: mask to apply to data before matching against @pattern
948 * @pattern: pattern to match (after mask is applied)
949 * @offset: offset into the adapter data from which to start scanning, returns
950 * the last scanned position.
951 * @size: number of bytes to scan from offset
952 * @value: pointer to uint32 to return matching data
954 * Scan for pattern @pattern with applied mask @mask in the adapter data,
955 * starting from offset @offset. If a match is found, the value that matched
956 * is returned through @value, otherwise @value is left untouched.
958 * The bytes in @pattern and @mask are interpreted left-to-right, regardless
959 * of endianness. All four bytes of the pattern must be present in the
960 * adapter for it to match, even if the first or last bytes are masked out.
962 * It is an error to call this function without making sure that there is
963 * enough data (offset+size bytes) in the adapter.
965 * Returns: offset of the first match, or -1 if no match was found.
970 gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask,
971 guint32 pattern, gsize offset, gsize size, guint32 * value)
974 gsize skip, bsize, i;
980 g_return_val_if_fail (size > 0, -1);
981 g_return_val_if_fail (offset + size <= adapter->size, -1);
982 g_return_val_if_fail (((~mask) & pattern) == 0, -1);
984 /* we can't find the pattern with less than 4 bytes */
985 if (G_UNLIKELY (size < 4))
988 skip = offset + adapter->skip;
990 /* first step, do skipping and position on the first buffer */
991 /* optimistically assume scanning continues sequentially */
992 if (adapter->priv->scan_entry && (adapter->priv->scan_offset <= skip)) {
993 g = adapter->priv->scan_entry;
994 skip -= adapter->priv->scan_offset;
996 g = adapter->buflist;
997 adapter->priv->scan_offset = 0;
998 adapter->priv->scan_entry = NULL;
1001 bsize = gst_buffer_get_size (buf);
1002 while (G_UNLIKELY (skip >= bsize)) {
1004 g = g_slist_next (g);
1005 adapter->priv->scan_offset += bsize;
1006 adapter->priv->scan_entry = g;
1008 bsize = gst_buffer_get_size (buf);
1010 /* get the data now */
1011 if (!gst_buffer_map (buf, &info, GST_MAP_READ))
1014 bdata = (guint8 *) info.data + skip;
1015 bsize = info.size - skip;
1018 /* set the state to something that does not match */
1023 bsize = MIN (bsize, size);
1024 for (i = 0; i < bsize; i++) {
1025 state = ((state << 8) | bdata[i]);
1026 if (G_UNLIKELY ((state & mask) == pattern)) {
1027 /* we have a match but we need to have skipped at
1028 * least 4 bytes to fill the state. */
1029 if (G_LIKELY (skip + i >= 3)) {
1030 if (G_LIKELY (value))
1032 gst_buffer_unmap (buf, &info);
1033 return offset + skip + i - 3;
1041 /* nothing found yet, go to next buffer */
1043 g = g_slist_next (g);
1044 adapter->priv->scan_offset += info.size;
1045 adapter->priv->scan_entry = g;
1046 gst_buffer_unmap (buf, &info);
1049 gst_buffer_map (buf, &info, GST_MAP_READ);
1054 gst_buffer_unmap (buf, &info);
1061 * gst_adapter_masked_scan_uint32:
1062 * @adapter: a #GstAdapter
1063 * @mask: mask to apply to data before matching against @pattern
1064 * @pattern: pattern to match (after mask is applied)
1065 * @offset: offset into the adapter data from which to start scanning, returns
1066 * the last scanned position.
1067 * @size: number of bytes to scan from offset
1069 * Scan for pattern @pattern with applied mask @mask in the adapter data,
1070 * starting from offset @offset.
1072 * The bytes in @pattern and @mask are interpreted left-to-right, regardless
1073 * of endianness. All four bytes of the pattern must be present in the
1074 * adapter for it to match, even if the first or last bytes are masked out.
1076 * It is an error to call this function without making sure that there is
1077 * enough data (offset+size bytes) in the adapter.
1079 * This function calls gst_adapter_masked_scan_uint32_peek() passing NULL
1082 * Returns: offset of the first match, or -1 if no match was found.
1086 * // Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff
1088 * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256);
1090 * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255);
1092 * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255);
1094 * gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256);
1096 * gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256);
1098 * gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256);
1100 * gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4);
1107 gst_adapter_masked_scan_uint32 (GstAdapter * adapter, guint32 mask,
1108 guint32 pattern, gsize offset, gsize size)
1110 return gst_adapter_masked_scan_uint32_peek (adapter, mask, pattern, offset,