gst/gstbuffer.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstbuffer.c: Buffer operations
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstbuffer
  25  * @short_description: Data-passing buffer type
  26  * @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
  27  *
  28  * Buffers are the basic unit of data transfer in GStreamer. They contain the
  29  * timing and offset along with other arbitrary metadata that is associated
  30  * with the #GstMemory blocks that the buffer contains.
  31  *
  32  * Buffers are usually created with gst_buffer_new(). After a buffer has been
  33  * created one will typically allocate memory for it and add it to the buffer.
  34  * The following example creates a buffer that can hold a given video frame
  35  * with a given width, height and bits per plane.
  36  * <example>
  37  * <title>Creating a buffer for a video frame</title>
  38  *   <programlisting>
  39  *   GstBuffer *buffer;
  40  *   GstMemory *memory;
  41  *   gint size, width, height, bpp;
  42  *   ...
  43  *   size = width * height * bpp;
  44  *   buffer = gst_buffer_new ();
  45  *   memory = gst_allocator_alloc (NULL, size, NULL);
  46  *   gst_buffer_insert_memory (buffer, -1, memory);
  47  *   ...
  48  *   </programlisting>
  49  * </example>
  50  *
  51  * Alternatively, use gst_buffer_new_allocate()
  52  * to create a buffer with preallocated data of a given size.
  53  *
  54  * Buffers can contain a list of #GstMemory objects. You can retrieve how many
  55  * memory objects with gst_buffer_n_memory() and you can get a pointer
  56  * to memory with gst_buffer_peek_memory()
  57  *
  58  * A buffer will usually have timestamps, and a duration, but neither of these
  59  * are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a
  60  * meaningful value can be given for these, they should be set. The timestamps
  61  * and duration are measured in nanoseconds (they are #GstClockTime values).
  62  *
  63  * The buffer DTS refers to the timestamp when the buffer should be decoded and
  64  * is usually monotonically increasing. The buffer PTS refers to the timestamp when
  65  * the buffer content should be presented to the user and is not always
  66  * monotonically increasing.
  67  *
  68  * A buffer can also have one or both of a start and an end offset. These are
  69  * media-type specific. For video buffers, the start offset will generally be
  70  * the frame number. For audio buffers, it will be the number of samples
  71  * produced so far. For compressed data, it could be the byte offset in a
  72  * source or destination file. Likewise, the end offset will be the offset of
  73  * the end of the buffer. These can only be meaningfully interpreted if you
  74  * know the media type of the buffer (the preceeding CAPS event). Either or both
  75  * can be set to #GST_BUFFER_OFFSET_NONE.
  76  *
  77  * gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  78  * done when you want to keep a handle to the buffer after pushing it to the
  79  * next element. The buffer refcount determines the writability of the buffer, a
  80  * buffer is only writable when the refcount is exactly 1, i.e. when the caller
  81  * has the only reference to the buffer.
  82  *
  83  * To efficiently create a smaller buffer out of an existing one, you can
  84  * use gst_buffer_copy_region(). This method tries to share the memory objects
  85  * between the two buffers.
  86  *
  87  * If a plug-in wants to modify the buffer data or metadata in-place, it should
  88  * first obtain a buffer that is safe to modify by using
  89  * gst_buffer_make_writable().  This function is optimized so that a copy will
  90  * only be made when it is necessary.
  91  *
  92  * Several flags of the buffer can be set and unset with the
  93  * GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use
  94  * GST_BUFFER_FLAG_IS_SET() to test if a certain #GstBufferFlag is set.
  95  *
  96  * Buffers can be efficiently merged into a larger buffer with
  97  * gst_buffer_append(). Copying of memory will only be done when absolutely
  98  * needed.
  99  *
 100  * Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta().
 101  * Metadata can be retrieved with gst_buffer_get_meta(). See also #GstMeta
 102  *
 103  * An element should either unref the buffer or push it out on a src pad
 104  * using gst_pad_push() (see #GstPad).
 105  *
 106  * Buffers are usually freed by unreffing them with gst_buffer_unref(). When
 107  * the refcount drops to 0, any memory and metadata pointed to by the buffer is
 108  * unreffed as well. Buffers allocated from a #GstBufferPool will be returned to
 109  * the pool when the refcount drops to 0.
 110  *
 111  * Last reviewed on 2012-03-28 (0.11.3)
 112  */
 113 #include "gst_private.h"
 114
 115 #ifdef HAVE_UNISTD_H
 116 #include <unistd.h>
 117 #endif
 118 #ifdef HAVE_STDLIB_H
 119 #include <stdlib.h>
 120 #endif
 121
 122 #include "gstbuffer.h"
 123 #include "gstbufferpool.h"
 124 #include "gstinfo.h"
 125 #include "gstutils.h"
 126 #include "gstversion.h"
 127
 128 GType _gst_buffer_type = 0;
 129
 130 typedef struct _GstMetaItem GstMetaItem;
 131
 132 struct _GstMetaItem
 133 {
 134   GstMetaItem *next;
 135   GstMeta meta;
 136 };
 137 #define ITEM_SIZE(info) ((info)->size + sizeof (GstMetaItem))
 138
 139 #define GST_BUFFER_MEM_MAX         16
 140
 141 #define GST_BUFFER_SLICE_SIZE(b)   (((GstBufferImpl *)(b))->slice_size)
 142 #define GST_BUFFER_MEM_LEN(b)      (((GstBufferImpl *)(b))->len)
 143 #define GST_BUFFER_MEM_ARRAY(b)    (((GstBufferImpl *)(b))->mem)
 144 #define GST_BUFFER_MEM_PTR(b,i)    (((GstBufferImpl *)(b))->mem[i])
 145 #define GST_BUFFER_BUFMEM(b)       (((GstBufferImpl *)(b))->bufmem)
 146 #define GST_BUFFER_META(b)         (((GstBufferImpl *)(b))->item)
 147
 148 typedef struct
 149 {
 150   GstBuffer buffer;
 151
 152   gsize slice_size;
 153
 154   /* the memory blocks */
 155   guint len;
 156   GstMemory *mem[GST_BUFFER_MEM_MAX];
 157
 158   /* memory of the buffer when allocated from 1 chunk */
 159   GstMemory *bufmem;
 160
 161   /* FIXME, make metadata allocation more efficient by using part of the
 162    * GstBufferImpl */
 163   GstMetaItem *item;
 164 } GstBufferImpl;
 165
 166
 167 static gboolean
 168 _is_span (GstMemory ** mem, gsize len, gsize * poffset, GstMemory ** parent)
 169 {
 170   GstMemory *mcur, *mprv;
 171   gboolean have_offset = FALSE;
 172   gsize i;
 173
 174   mcur = mprv = NULL;
 175
 176   for (i = 0; i < len; i++) {
 177     if (mcur)
 178       mprv = mcur;
 179     mcur = mem[i];
 180
 181     if (mprv && mcur) {
 182       gsize poffs;
 183
 184       /* check if memory is contiguous */
 185       if (!gst_memory_is_span (mprv, mcur, &poffs))
 186         return FALSE;
 187
 188       if (!have_offset) {
 189         if (poffset)
 190           *poffset = poffs;
 191         if (parent)
 192           *parent = mprv->parent;
 193
 194         have_offset = TRUE;
 195       }
 196     }
 197   }
 198   return have_offset;
 199 }
 200
 201 static GstMemory *
 202 _get_merged_memory (GstBuffer * buffer, guint idx, guint length)
 203 {
 204   GstMemory **mem, *result;
 205
 206   mem = GST_BUFFER_MEM_ARRAY (buffer);
 207
 208   if (G_UNLIKELY (length == 0)) {
 209     result = NULL;
 210   } else if (G_LIKELY (length == 1)) {
 211     result = gst_memory_ref (mem[idx]);
 212   } else {
 213     GstMemory *parent = NULL;
 214     gsize size, poffset = 0;
 215
 216     size = gst_buffer_get_size (buffer);
 217
 218     if (G_UNLIKELY (_is_span (mem + idx, length, &poffset, &parent))) {
 219
 220       if (GST_MEMORY_IS_NO_SHARE (parent)) {
 221         GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy for merge %p", parent);
 222         result = gst_memory_copy (parent, poffset, size);
 223       } else {
 224         result = gst_memory_share (parent, poffset, size);
 225       }
 226     } else {
 227       gsize i, tocopy, left;
 228       GstMapInfo sinfo, dinfo;
 229       guint8 *ptr;
 230
 231       result = gst_allocator_alloc (NULL, size, NULL);
 232       gst_memory_map (result, &dinfo, GST_MAP_WRITE);
 233
 234       ptr = dinfo.data;
 235       left = size;
 236
 237       for (i = idx; i < length && left > 0; i++) {
 238         gst_memory_map (mem[i], &sinfo, GST_MAP_READ);
 239         tocopy = MIN (sinfo.size, left);
 240         GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
 241             "memcpy %" G_GSIZE_FORMAT " bytes for merge %p from memory %p",
 242             tocopy, result, mem[i]);
 243         memcpy (ptr, (guint8 *) sinfo.data, tocopy);
 244         left -= tocopy;
 245         ptr += tocopy;
 246         gst_memory_unmap (mem[i], &sinfo);
 247       }
 248       gst_memory_unmap (result, &dinfo);
 249     }
 250   }
 251   return result;
 252 }
 253
 254 static void
 255 _replace_memory (GstBuffer * buffer, guint len, guint idx, guint length,
 256     GstMemory * mem)
 257 {
 258   gsize end, i;
 259
 260   end = idx + length;
 261   GST_LOG ("buffer %p replace %u-%" G_GSIZE_FORMAT " with memory %p", buffer,
 262       idx, end, mem);
 263
 264   /* unref old memory */
 265   for (i = idx; i < end; i++)
 266     gst_memory_unref (GST_BUFFER_MEM_PTR (buffer, i));
 267
 268   if (mem != NULL) {
 269     /* replace with single memory */
 270     GST_BUFFER_MEM_PTR (buffer, idx) = mem;
 271     idx++;
 272     length--;
 273   }
 274
 275   if (end < len) {
 276     g_memmove (&GST_BUFFER_MEM_PTR (buffer, idx),
 277         &GST_BUFFER_MEM_PTR (buffer, end), (len - end) * sizeof (gpointer));
 278   }
 279   GST_BUFFER_MEM_LEN (buffer) = len - length;
 280 }
 281
 282 static inline void
 283 _memory_add (GstBuffer * buffer, guint idx, GstMemory * mem)
 284 {
 285   guint i, len = GST_BUFFER_MEM_LEN (buffer);
 286
 287   if (G_UNLIKELY (len >= GST_BUFFER_MEM_MAX)) {
 288     /* too many buffer, span them. */
 289     /* FIXME, there is room for improvement here: We could only try to merge
 290      * 2 buffers to make some room. If we can't efficiently merge 2 buffers we
 291      * could try to only merge the two smallest buffers to avoid memcpy, etc. */
 292     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "memory array overflow in buffer %p",
 293         buffer);
 294     _replace_memory (buffer, len, 0, len, _get_merged_memory (buffer, 0, len));
 295     /* we now have 1 single spanned buffer */
 296     len = 1;
 297   }
 298
 299   if (idx == -1)
 300     idx = len;
 301
 302   for (i = len; i > idx; i--) {
 303     /* move buffers to insert, FIXME, we need to insert first and then merge */
 304     GST_BUFFER_MEM_PTR (buffer, i) = GST_BUFFER_MEM_PTR (buffer, i - 1);
 305   }
 306   /* and insert the new buffer */
 307   GST_BUFFER_MEM_PTR (buffer, idx) = mem;
 308   GST_BUFFER_MEM_LEN (buffer) = len + 1;
 309 }
 310
 311 GST_DEFINE_MINI_OBJECT_TYPE (GstBuffer, gst_buffer);
 312
 313 void
 314 _priv_gst_buffer_initialize (void)
 315 {
 316   _gst_buffer_type = gst_buffer_get_type ();
 317 }
 318
 319 /**
 320  * gst_buffer_copy_into:
 321  * @dest: a destination #GstBuffer
 322  * @src: a source #GstBuffer
 323  * @flags: flags indicating what metadata fields should be copied.
 324  * @offset: offset to copy from
 325  * @size: total size to copy. If -1, all data is copied.
 326  *
 327  * Copies the information from @src into @dest.
 328  *
 329  * If @dest already contains memory and @flags contains GST_BUFFER_COPY_MEMORY,
 330  * the memory from @src will be appended to @dest.
 331  *
 332  * @flags indicate which fields will be copied.
 333  */
 334 void
 335 gst_buffer_copy_into (GstBuffer * dest, GstBuffer * src,
 336     GstBufferCopyFlags flags, gsize offset, gsize size)
 337 {
 338   GstMetaItem *walk;
 339   gsize bufsize;
 340   gboolean region = FALSE;
 341
 342   g_return_if_fail (dest != NULL);
 343   g_return_if_fail (src != NULL);
 344
 345   /* nothing to copy if the buffers are the same */
 346   if (G_UNLIKELY (dest == src))
 347     return;
 348
 349   g_return_if_fail (gst_buffer_is_writable (dest));
 350
 351   bufsize = gst_buffer_get_size (src);
 352   g_return_if_fail (bufsize >= offset);
 353   if (offset > 0)
 354     region = TRUE;
 355   if (size == -1)
 356     size = bufsize - offset;
 357   if (size < bufsize)
 358     region = TRUE;
 359   g_return_if_fail (bufsize >= offset + size);
 360
 361   GST_CAT_LOG (GST_CAT_BUFFER, "copy %p to %p, offset %" G_GSIZE_FORMAT
 362       "-%" G_GSIZE_FORMAT "/%" G_GSIZE_FORMAT, src, dest, offset, size,
 363       bufsize);
 364
 365   if (flags & GST_BUFFER_COPY_FLAGS) {
 366     /* copy flags */
 367     GST_MINI_OBJECT_FLAGS (dest) = GST_MINI_OBJECT_FLAGS (src);
 368   }
 369
 370   if (flags & GST_BUFFER_COPY_TIMESTAMPS) {
 371     if (offset == 0) {
 372       GST_BUFFER_PTS (dest) = GST_BUFFER_PTS (src);
 373       GST_BUFFER_DTS (dest) = GST_BUFFER_DTS (src);
 374       GST_BUFFER_OFFSET (dest) = GST_BUFFER_OFFSET (src);
 375       if (size == bufsize) {
 376         GST_BUFFER_DURATION (dest) = GST_BUFFER_DURATION (src);
 377         GST_BUFFER_OFFSET_END (dest) = GST_BUFFER_OFFSET_END (src);
 378       }
 379     } else {
 380       GST_BUFFER_PTS (dest) = GST_CLOCK_TIME_NONE;
 381       GST_BUFFER_DTS (dest) = GST_CLOCK_TIME_NONE;
 382       GST_BUFFER_DURATION (dest) = GST_CLOCK_TIME_NONE;
 383       GST_BUFFER_OFFSET (dest) = GST_BUFFER_OFFSET_NONE;
 384       GST_BUFFER_OFFSET_END (dest) = GST_BUFFER_OFFSET_NONE;
 385     }
 386   }
 387
 388   if (flags & GST_BUFFER_COPY_MEMORY) {
 389     GstMemory *mem;
 390     gsize skip, left, len, i, bsize;
 391
 392     len = GST_BUFFER_MEM_LEN (src);
 393     left = size;
 394     skip = offset;
 395
 396     /* copy and make regions of the memory */
 397     for (i = 0; i < len && left > 0; i++) {
 398       mem = GST_BUFFER_MEM_PTR (src, i);
 399       bsize = gst_memory_get_sizes (mem, NULL, NULL);
 400
 401       if (bsize <= skip) {
 402         /* don't copy buffer */
 403         skip -= bsize;
 404       } else {
 405         gsize tocopy;
 406
 407         tocopy = MIN (bsize - skip, left);
 408         if (GST_MEMORY_IS_NO_SHARE (mem)) {
 409           /* no share, always copy then */
 410           mem = gst_memory_copy (mem, skip, tocopy);
 411           skip = 0;
 412         } else if (tocopy < bsize) {
 413           /* we need to clip something */
 414           mem = gst_memory_share (mem, skip, tocopy);
 415           skip = 0;
 416         } else {
 417           mem = gst_memory_ref (mem);
 418         }
 419         _memory_add (dest, -1, mem);
 420         left -= tocopy;
 421       }
 422     }
 423     if (flags & GST_BUFFER_COPY_MERGE) {
 424       len = GST_BUFFER_MEM_LEN (dest);
 425       _replace_memory (dest, len, 0, len, _get_merged_memory (dest, 0, len));
 426     }
 427   }
 428
 429   if (flags & GST_BUFFER_COPY_META) {
 430     for (walk = GST_BUFFER_META (src); walk; walk = walk->next) {
 431       GstMeta *meta = &walk->meta;
 432       const GstMetaInfo *info = meta->info;
 433
 434       if (info->transform_func) {
 435         GstMetaTransformCopy copy_data;
 436
 437         copy_data.region = region;
 438         copy_data.offset = offset;
 439         copy_data.size = size;
 440
 441         info->transform_func (dest, meta, src,
 442             _gst_meta_transform_copy, &copy_data);
 443       }
 444     }
 445   }
 446 }
 447
 448 static GstBuffer *
 449 _gst_buffer_copy (GstBuffer * buffer)
 450 {
 451   GstBuffer *copy;
 452
 453   g_return_val_if_fail (buffer != NULL, NULL);
 454
 455   /* create a fresh new buffer */
 456   copy = gst_buffer_new ();
 457
 458   /* we simply copy everything from our parent */
 459   gst_buffer_copy_into (copy, buffer, GST_BUFFER_COPY_ALL, 0, -1);
 460
 461   return copy;
 462 }
 463
 464 /* the default dispose function revives the buffer and returns it to the
 465  * pool when there is a pool */
 466 static gboolean
 467 _gst_buffer_dispose (GstBuffer * buffer)
 468 {
 469   GstBufferPool *pool;
 470
 471   /* no pool, do free */
 472   if ((pool = buffer->pool) == NULL)
 473     return TRUE;
 474
 475   /* keep the buffer alive */
 476   gst_buffer_ref (buffer);
 477   /* return the buffer to the pool */
 478   GST_CAT_LOG (GST_CAT_BUFFER, "release %p to pool %p", buffer, pool);
 479   gst_buffer_pool_release_buffer (pool, buffer);
 480
 481   return FALSE;
 482 }
 483
 484 static void
 485 _gst_buffer_free (GstBuffer * buffer)
 486 {
 487   GstMetaItem *walk, *next;
 488   guint i, len;
 489   gsize msize;
 490
 491   g_return_if_fail (buffer != NULL);
 492
 493   GST_CAT_LOG (GST_CAT_BUFFER, "finalize %p", buffer);
 494
 495   /* free metadata */
 496   for (walk = GST_BUFFER_META (buffer); walk; walk = next) {
 497     GstMeta *meta = &walk->meta;
 498     const GstMetaInfo *info = meta->info;
 499
 500     /* call free_func if any */
 501     if (info->free_func)
 502       info->free_func (meta, buffer);
 503
 504     next = walk->next;
 505     /* and free the slice */
 506     g_slice_free1 (ITEM_SIZE (info), walk);
 507   }
 508
 509   /* get the size, when unreffing the memory, we could also unref the buffer
 510    * itself */
 511   msize = GST_BUFFER_SLICE_SIZE (buffer);
 512
 513   /* free our memory */
 514   len = GST_BUFFER_MEM_LEN (buffer);
 515   for (i = 0; i < len; i++)
 516     gst_memory_unref (GST_BUFFER_MEM_PTR (buffer, i));
 517
 518   /* we set msize to 0 when the buffer is part of the memory block */
 519   if (msize)
 520     g_slice_free1 (msize, buffer);
 521   else
 522     gst_memory_unref (GST_BUFFER_BUFMEM (buffer));
 523 }
 524
 525 static void
 526 gst_buffer_init (GstBufferImpl * buffer, gsize size)
 527 {
 528   gst_mini_object_init (GST_MINI_OBJECT_CAST (buffer), _gst_buffer_type);
 529
 530   buffer->buffer.mini_object.copy =
 531       (GstMiniObjectCopyFunction) _gst_buffer_copy;
 532   buffer->buffer.mini_object.dispose =
 533       (GstMiniObjectDisposeFunction) _gst_buffer_dispose;
 534   buffer->buffer.mini_object.free =
 535       (GstMiniObjectFreeFunction) _gst_buffer_free;
 536
 537   GST_BUFFER_SLICE_SIZE (buffer) = size;
 538
 539   GST_BUFFER (buffer)->pool = NULL;
 540   GST_BUFFER_PTS (buffer) = GST_CLOCK_TIME_NONE;
 541   GST_BUFFER_DTS (buffer) = GST_CLOCK_TIME_NONE;
 542   GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
 543   GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
 544   GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
 545
 546   GST_BUFFER_MEM_LEN (buffer) = 0;
 547   GST_BUFFER_META (buffer) = NULL;
 548 }
 549
 550 /**
 551  * gst_buffer_new:
 552  *
 553  * Creates a newly allocated buffer without any data.
 554  *
 555  * MT safe.
 556  *
 557  * Returns: (transfer full): the new #GstBuffer.
 558  */
 559 GstBuffer *
 560 gst_buffer_new (void)
 561 {
 562   GstBufferImpl *newbuf;
 563
 564   newbuf = g_slice_new (GstBufferImpl);
 565   GST_CAT_LOG (GST_CAT_BUFFER, "new %p", newbuf);
 566
 567   gst_buffer_init (newbuf, sizeof (GstBufferImpl));
 568
 569   return GST_BUFFER_CAST (newbuf);
 570 }
 571
 572 /**
 573  * gst_buffer_new_allocate:
 574  * @allocator: (transfer none) (allow-none): the #GstAllocator to use, or NULL to use the
 575  *     default allocator
 576  * @size: the size in bytes of the new buffer's data.
 577  * @params: (transfer none) (allow-none): optional parameters
 578  *
 579  * Tries to create a newly allocated buffer with data of the given size and
 580  * extra parameters from @allocator. If the requested amount of memory can't be
 581  * allocated, NULL will be returned. The allocated buffer memory is not cleared.
 582  *
 583  * When @allocator is NULL, the default memory allocator will be used.
 584  *
 585  * Note that when @size == 0, the buffer will not have memory associated with it.
 586  *
 587  * MT safe.
 588  *
 589  * Returns: (transfer full): a new #GstBuffer, or NULL if the memory couldn't
 590  *     be allocated.
 591  */
 592 GstBuffer *
 593 gst_buffer_new_allocate (GstAllocator * allocator, gsize size,
 594     GstAllocationParams * params)
 595 {
 596   GstBuffer *newbuf;
 597   GstMemory *mem;
 598 #if 0
 599   guint8 *data;
 600   gsize asize;
 601 #endif
 602
 603 #if 1
 604   if (size > 0) {
 605     mem = gst_allocator_alloc (allocator, size, params);
 606     if (G_UNLIKELY (mem == NULL))
 607       goto no_memory;
 608   } else {
 609     mem = NULL;
 610   }
 611
 612   newbuf = gst_buffer_new ();
 613
 614   if (mem != NULL)
 615     _memory_add (newbuf, -1, mem);
 616
 617   GST_CAT_LOG (GST_CAT_BUFFER,
 618       "new buffer %p of size %" G_GSIZE_FORMAT " from allocator %p", newbuf,
 619       size, allocator);
 620 #endif
 621
 622 #if 0
 623   asize = sizeof (GstBufferImpl) + size;
 624   data = g_slice_alloc (asize);
 625   if (G_UNLIKELY (data == NULL))
 626     goto no_memory;
 627
 628   newbuf = GST_BUFFER_CAST (data);
 629
 630   gst_buffer_init ((GstBufferImpl *) data, asize);
 631   if (size > 0) {
 632     mem = gst_memory_new_wrapped (0, data + sizeof (GstBufferImpl), NULL,
 633         size, 0, size);
 634     _memory_add (newbuf, -1, mem);
 635   }
 636 #endif
 637
 638 #if 0
 639   /* allocate memory and buffer, it might be interesting to do this but there
 640    * are many complications. We need to keep the memory mapped to access the
 641    * buffer fields and the memory for the buffer might be just very slow. We
 642    * also need to do some more magic to get the alignment right. */
 643   asize = sizeof (GstBufferImpl) + size;
 644   mem = gst_allocator_alloc (allocator, asize, align);
 645   if (G_UNLIKELY (mem == NULL))
 646     goto no_memory;
 647
 648   /* map the data part and init the buffer in it, set the buffer size to 0 so
 649    * that a finalize won't free the buffer */
 650   data = gst_memory_map (mem, &asize, NULL, GST_MAP_WRITE);
 651   gst_buffer_init ((GstBufferImpl *) data, 0);
 652   gst_memory_unmap (mem);
 653
 654   /* strip off the buffer */
 655   gst_memory_resize (mem, sizeof (GstBufferImpl), size);
 656
 657   newbuf = GST_BUFFER_CAST (data);
 658   GST_BUFFER_BUFMEM (newbuf) = mem;
 659
 660   if (size > 0)
 661     _memory_add (newbuf, -1, gst_memory_ref (mem));
 662 #endif
 663
 664   return newbuf;
 665
 666   /* ERRORS */
 667 no_memory:
 668   {
 669     GST_CAT_WARNING (GST_CAT_BUFFER,
 670         "failed to allocate %" G_GSIZE_FORMAT " bytes", size);
 671     return NULL;
 672   }
 673 }
 674
 675 /**
 676  * gst_buffer_new_wrapped_full:
 677  * @flags: #GstMemoryFlags
 678  * @data: data to wrap
 679  * @maxsize: allocated size of @data
 680  * @offset: offset in @data
 681  * @size: size of valid data
 682  * @user_data: user_data
 683  * @notify: called with @user_data when the memory is freed
 684  *
 685  * Allocate a new buffer that wraps the given memory. @data must point to
 686  * @maxsize of memory, the wrapped buffer will have the region from @offset and
 687  * @size visible.
 688  *
 689  * When the buffer is destroyed, @notify will be called with @user_data.
 690  *
 691  * The prefix/padding must be filled with 0 if @flags contains
 692  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 693  *
 694  * Returns: (transfer full): a new #GstBuffer
 695  */
 696 GstBuffer *
 697 gst_buffer_new_wrapped_full (GstMemoryFlags flags, gpointer data,
 698     gsize maxsize, gsize offset, gsize size, gpointer user_data,
 699     GDestroyNotify notify)
 700 {
 701   GstBuffer *newbuf;
 702
 703   newbuf = gst_buffer_new ();
 704   gst_buffer_append_memory (newbuf,
 705       gst_memory_new_wrapped (flags, data, maxsize, offset, size,
 706           user_data, notify));
 707
 708   return newbuf;
 709 }
 710
 711 /**
 712  * gst_buffer_new_wrapped:
 713  * @data: data to wrap
 714  * @size: allocated size of @data
 715  *
 716  * Creates a new buffer that wraps the given @data. The memory will be freed
 717  * with g_free and will be marked writable.
 718  *
 719  * MT safe.
 720  *
 721  * Returns: (transfer full): a new #GstBuffer
 722  */
 723 GstBuffer *
 724 gst_buffer_new_wrapped (gpointer data, gsize size)
 725 {
 726   return gst_buffer_new_wrapped_full (0, data, size, 0, size, data, g_free);
 727 }
 728
 729 /**
 730  * gst_buffer_n_memory:
 731  * @buffer: a #GstBuffer.
 732  *
 733  * Get the amount of memory blocks that this buffer has.
 734  *
 735  * Returns: (transfer full): the amount of memory block in this buffer.
 736  */
 737 guint
 738 gst_buffer_n_memory (GstBuffer * buffer)
 739 {
 740   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
 741
 742   return GST_BUFFER_MEM_LEN (buffer);
 743 }
 744
 745 /**
 746  * gst_buffer_insert_memory:
 747  * @buffer: a #GstBuffer.
 748  * @idx: the index to add the memory at, or -1 to append it to the end
 749  * @mem: (transfer full): a #GstMemory.
 750  *
 751  * Insert the memory block @mem to @buffer at @idx. This function takes ownership
 752  * of @mem and thus doesn't increase its refcount.
 753  */
 754 void
 755 gst_buffer_insert_memory (GstBuffer * buffer, gint idx, GstMemory * mem)
 756 {
 757   g_return_if_fail (GST_IS_BUFFER (buffer));
 758   g_return_if_fail (gst_buffer_is_writable (buffer));
 759   g_return_if_fail (mem != NULL);
 760   g_return_if_fail (idx == -1 ||
 761       (idx >= 0 && idx <= GST_BUFFER_MEM_LEN (buffer)));
 762
 763   _memory_add (buffer, idx, mem);
 764 }
 765
 766 static GstMemory *
 767 _get_mapped (GstBuffer * buffer, guint idx, GstMapInfo * info,
 768     GstMapFlags flags)
 769 {
 770   GstMemory *mem, *mapped;
 771
 772   mem = GST_BUFFER_MEM_PTR (buffer, idx);
 773
 774   mapped = gst_memory_make_mapped (mem, info, flags);
 775   if (!mapped)
 776     return NULL;
 777
 778   if (mapped != mem) {
 779     GST_BUFFER_MEM_PTR (buffer, idx) = mapped;
 780     gst_memory_unref (mem);
 781     mem = mapped;
 782   }
 783   return mem;
 784 }
 785
 786 /**
 787  * gst_buffer_peek_memory:
 788  * @buffer: a #GstBuffer.
 789  * @idx: an index
 790  *
 791  * Get the memory block at @idx in @buffer. The memory block stays valid until
 792  * the memory block in @buffer is removed, replaced or merged, typically with
 793  * any call that modifies the memory in @buffer.
 794  *
 795  * Since this call does not influence the refcount of the memory,
 796  * gst_memory_is_exclusive() can be used to check if @buffer is the sole owner
 797  * of the returned memory.
 798  *
 799  * Returns: (transfer none): the #GstMemory at @idx.
 800  */
 801 GstMemory *
 802 gst_buffer_peek_memory (GstBuffer * buffer, guint idx)
 803 {
 804   guint len;
 805
 806   g_return_val_if_fail (GST_IS_BUFFER (buffer), NULL);
 807   len = GST_BUFFER_MEM_LEN (buffer);
 808   g_return_val_if_fail (idx < len, NULL);
 809
 810   return GST_BUFFER_MEM_PTR (buffer, idx);
 811 }
 812
 813 /**
 814  * gst_buffer_get_memory_range:
 815  * @buffer: a #GstBuffer.
 816  * @idx: an index
 817  * @length: a length
 818  *
 819  * Get @length memory blocks in @buffer starting at @idx. The memory blocks will
 820  * be merged into one large #GstMemory.
 821  *
 822  * If @length is -1, all memory starting from @idx is merged.
 823  *
 824  * Returns: (transfer full): a #GstMemory that contains the merged data of @length
 825  *    blocks starting at @idx. Use gst_memory_unref () after usage.
 826  */
 827 GstMemory *
 828 gst_buffer_get_memory_range (GstBuffer * buffer, guint idx, gint length)
 829 {
 830   guint len;
 831
 832   GST_DEBUG ("idx %u, length %d", idx, length);
 833
 834   g_return_val_if_fail (GST_IS_BUFFER (buffer), NULL);
 835   len = GST_BUFFER_MEM_LEN (buffer);
 836   g_return_val_if_fail ((len == 0 && idx == 0 && length == -1) ||
 837       (length == -1 && idx < len) || (length > 0 && length + idx <= len), NULL);
 838
 839   if (length == -1)
 840     length = len - idx;
 841
 842   return _get_merged_memory (buffer, idx, length);
 843 }
 844
 845 /**
 846  * gst_buffer_replace_memory_range:
 847  * @buffer: a #GstBuffer.
 848  * @idx: an index
 849  * @length: a length should not be 0
 850  * @mem: (transfer full): a #GstMemory
 851  *
 852  * Replaces @length memory blocks in @buffer starting at @idx with @mem.
 853  *
 854  * If @length is -1, all memory starting from @idx will be removed and
 855  * replaced with @mem.
 856  *
 857  * @buffer should be writable.
 858  */
 859 void
 860 gst_buffer_replace_memory_range (GstBuffer * buffer, guint idx, gint length,
 861     GstMemory * mem)
 862 {
 863   guint len;
 864
 865   g_return_if_fail (GST_IS_BUFFER (buffer));
 866   g_return_if_fail (gst_buffer_is_writable (buffer));
 867   len = GST_BUFFER_MEM_LEN (buffer);
 868   g_return_if_fail ((len == 0 && idx == 0 && length == -1) ||
 869       (length == -1 && idx < len) || (length > 0 && length + idx <= len));
 870
 871   if (length == -1)
 872     length = len - idx;
 873
 874   _replace_memory (buffer, len, idx, length, mem);
 875 }
 876
 877 /**
 878  * gst_buffer_remove_memory_range:
 879  * @buffer: a #GstBuffer.
 880  * @idx: an index
 881  * @length: a length
 882  *
 883  * Remove @length memory blocks in @buffer starting from @idx.
 884  *
 885  * @length can be -1, in which case all memory starting from @idx is removed.
 886  */
 887 void
 888 gst_buffer_remove_memory_range (GstBuffer * buffer, guint idx, gint length)
 889 {
 890   guint len;
 891
 892   g_return_if_fail (GST_IS_BUFFER (buffer));
 893   g_return_if_fail (gst_buffer_is_writable (buffer));
 894
 895   len = GST_BUFFER_MEM_LEN (buffer);
 896   g_return_if_fail ((len == 0 && idx == 0 && length == -1) ||
 897       (length == -1 && idx < len) || length + idx <= len);
 898
 899   if (length == -1)
 900     length = len - idx;
 901
 902   _replace_memory (buffer, len, idx, length, NULL);
 903 }
 904
 905 /**
 906  * gst_buffer_find_memory:
 907  * @buffer: a #GstBuffer.
 908  * @offset: an offset
 909  * @size: a size
 910  * @idx: (out): pointer to index
 911  * @length: (out): pointer to length
 912  * @skip: (out): pointer to skip
 913  *
 914  * Find the memory blocks that span @size bytes starting from @offset
 915  * in @buffer.
 916  *
 917  * When this function returns %TRUE, @idx will contain the index of the first
 918  * memory bock where the byte for @offset can be found and @length contains the
 919  * number of memory blocks containing the @size remaining bytes. @skip contains
 920  * the number of bytes to skip in the memory bock at @idx to get to the byte
 921  * for @offset.
 922  *
 923  * @size can be -1 to get all the memory blocks after @idx.
 924  *
 925  * Returns: %TRUE when @size bytes starting from @offset could be found in
 926  * @buffer and @idx, @length and @skip will be filled.
 927  */
 928 gboolean
 929 gst_buffer_find_memory (GstBuffer * buffer, gsize offset, gsize size,
 930     guint * idx, guint * length, gsize * skip)
 931 {
 932   guint i, len, found;
 933
 934   g_return_val_if_fail (GST_IS_BUFFER (buffer), FALSE);
 935   g_return_val_if_fail (idx != NULL, FALSE);
 936   g_return_val_if_fail (length != NULL, FALSE);
 937   g_return_val_if_fail (skip != NULL, FALSE);
 938
 939   len = GST_BUFFER_MEM_LEN (buffer);
 940
 941   found = 0;
 942   for (i = 0; i < len; i++) {
 943     GstMemory *mem;
 944     gsize s;
 945
 946     mem = GST_BUFFER_MEM_PTR (buffer, i);
 947     s = gst_memory_get_sizes (mem, NULL, NULL);
 948
 949     if (s <= offset) {
 950       /* block before offset, or empty block, skip */
 951       offset -= s;
 952     } else {
 953       /* block after offset */
 954       if (found == 0) {
 955         /* first block, remember index and offset */
 956         *idx = i;
 957         *skip = offset;
 958         if (size == -1) {
 959           /* return remaining blocks */
 960           *length = len - i;
 961           return TRUE;
 962         }
 963         s -= offset;
 964         offset = 0;
 965       }
 966       /* count the amount of found bytes */
 967       found += s;
 968       if (found >= size) {
 969         /* we have enough bytes */
 970         *length = i - *idx + 1;
 971         return TRUE;
 972       }
 973     }
 974   }
 975   return FALSE;
 976 }
 977
 978 /**
 979  * gst_buffer_get_sizes_range:
 980  * @buffer: a #GstBuffer.
 981  * @idx: an index
 982  * @length: a length
 983  * @offset: a pointer to the offset
 984  * @maxsize: a pointer to the maxsize
 985  *
 986  * Get the total size of @length memory blocks stating from @idx in @buffer.
 987  *
 988  * When not %NULL, @offset will contain the offset of the data in the
 989  * memory block in @buffer at @idx and @maxsize will contain the sum of the size
 990  * and @offset and the amount of extra padding on the memory block at @idx +
 991  * @length -1.
 992  * @offset and @maxsize can be used to resize the buffer memory blocks with
 993  * gst_buffer_resize_range().
 994  *
 995  * Returns: total size @length memory blocks starting at @idx in @buffer.
 996  */
 997 gsize
 998 gst_buffer_get_sizes_range (GstBuffer * buffer, guint idx, gint length,
 999     gsize * offset, gsize * maxsize)
1000 {
1001   guint len;
1002   gsize size;
1003   GstMemory *mem;
1004
1005   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
1006   len = GST_BUFFER_MEM_LEN (buffer);
1007   g_return_val_if_fail ((len == 0 && idx == 0 && length == -1) ||
1008       (length == -1 && idx < len) || (length + idx <= len), 0);
1009
1010   if (length == -1)
1011     length = len - idx;
1012
1013   if (G_LIKELY (length == 1)) {
1014     /* common case */
1015     mem = GST_BUFFER_MEM_PTR (buffer, idx);
1016     size = gst_memory_get_sizes (mem, offset, maxsize);
1017   } else {
1018     guint i, end;
1019     gsize extra, offs;
1020
1021     end = idx + length;
1022     size = offs = extra = 0;
1023     for (i = idx; i < end; i++) {
1024       gsize s, o, ms;
1025
1026       mem = GST_BUFFER_MEM_PTR (buffer, i);
1027       s = gst_memory_get_sizes (mem, &o, &ms);
1028
1029       if (s) {
1030         if (size == 0)
1031           /* first size, take accumulated data before as the offset */
1032           offs = extra + o;
1033         /* add sizes */
1034         size += s;
1035         /* save the amount of data after this block */
1036         extra = ms - (o + s);
1037       } else {
1038         /* empty block, add as extra */
1039         extra += ms;
1040       }
1041     }
1042     if (offset)
1043       *offset = offs;
1044     if (maxsize)
1045       *maxsize = offs + size + extra;
1046   }
1047   return size;
1048 }
1049
1050 /**
1051  * gst_buffer_resize_range:
1052  * @buffer: a #GstBuffer.
1053  * @idx: an index
1054  * @length: a length
1055  * @offset: the offset adjustement
1056  * @size: the new size or -1 to just adjust the offset
1057  *
1058  * Set the total size of the @length memory blocks starting at @idx in
1059  * @buffer
1060  */
1061 void
1062 gst_buffer_resize_range (GstBuffer * buffer, guint idx, gint length,
1063     gssize offset, gssize size)
1064 {
1065   guint i, len, end;
1066   gsize bsize, bufsize, bufoffs, bufmax;
1067   GstMemory *mem;
1068
1069   g_return_if_fail (gst_buffer_is_writable (buffer));
1070   g_return_if_fail (size >= -1);
1071   len = GST_BUFFER_MEM_LEN (buffer);
1072   g_return_if_fail ((len == 0 && idx == 0 && length == -1) ||
1073       (length == -1 && idx < len) || (length + idx <= len));
1074
1075   if (length == -1)
1076     length = len - idx;
1077
1078   bufsize = gst_buffer_get_sizes_range (buffer, idx, length, &bufoffs, &bufmax);
1079
1080   GST_CAT_LOG (GST_CAT_BUFFER, "trim %p %" G_GSSIZE_FORMAT "-%" G_GSSIZE_FORMAT
1081       " size:%" G_GSIZE_FORMAT " offs:%" G_GSIZE_FORMAT " max:%"
1082       G_GSIZE_FORMAT, buffer, offset, size, bufsize, bufoffs, bufmax);
1083
1084   /* we can't go back further than the current offset or past the end of the
1085    * buffer */
1086   g_return_if_fail ((offset < 0 && bufoffs >= -offset) || (offset >= 0
1087           && bufoffs + offset <= bufmax));
1088   if (size == -1) {
1089     g_return_if_fail (bufsize >= offset);
1090     size = bufsize - offset;
1091   }
1092   g_return_if_fail (bufmax >= bufoffs + offset + size);
1093
1094   /* no change */
1095   if (offset == 0 && size == bufsize)
1096     return;
1097
1098   end = idx + length;
1099   /* copy and trim */
1100   for (i = idx; i < end; i++) {
1101     gsize left, noffs;
1102
1103     mem = GST_BUFFER_MEM_PTR (buffer, i);
1104     bsize = gst_memory_get_sizes (mem, NULL, NULL);
1105
1106     noffs = 0;
1107     /* last buffer always gets resized to the remaining size */
1108     if (i + 1 == end)
1109       left = size;
1110     /* shrink buffers before the offset */
1111     else if ((gssize) bsize <= offset) {
1112       left = 0;
1113       noffs = offset - bsize;
1114       offset = 0;
1115     }
1116     /* clip other buffers */
1117     else
1118       left = MIN (bsize - offset, size);
1119
1120     if (offset != 0 || left != bsize) {
1121       if (gst_memory_is_exclusive (mem)) {
1122         gst_memory_resize (mem, offset, left);
1123       } else {
1124         GstMemory *tmp;
1125
1126         if (GST_MEMORY_IS_NO_SHARE (mem))
1127           tmp = gst_memory_copy (mem, offset, left);
1128         else
1129           tmp = gst_memory_share (mem, offset, left);
1130
1131         gst_memory_unref (mem);
1132         mem = tmp;
1133       }
1134     }
1135     offset = noffs;
1136     size -= left;
1137
1138     GST_BUFFER_MEM_PTR (buffer, i) = mem;
1139   }
1140 }
1141
1142 /**
1143  * gst_buffer_map_range:
1144  * @buffer: a #GstBuffer.
1145  * @idx: an index
1146  * @length: a length
1147  * @info: (out): info about the mapping
1148  * @flags: flags for the mapping
1149  *
1150  * This function fills @info with the #GstMapInfo of @length merged memory blocks
1151  * starting at @idx in @buffer. When @length is -1, all memory blocks starting
1152  * from @idx are merged and mapped.
1153  * @flags describe the desired access of the memory. When @flags is
1154  * #GST_MAP_WRITE, @buffer should be writable (as returned from
1155  * gst_buffer_is_writable()).
1156  *
1157  * When @buffer is writable but the memory isn't, a writable copy will
1158  * automatically be created and returned. The readonly copy of the buffer memory
1159  * will then also be replaced with this writable copy.
1160  *
1161  * The memory in @info should be unmapped with gst_buffer_unmap() after usage.
1162  *
1163  * Returns: (transfer full): %TRUE if the map succeeded and @info contains valid
1164  * data.
1165  */
1166 gboolean
1167 gst_buffer_map_range (GstBuffer * buffer, guint idx, gint length,
1168     GstMapInfo * info, GstMapFlags flags)
1169 {
1170   GstMemory *mem, *nmem;
1171   gboolean write, writable;
1172   gsize len;
1173
1174   g_return_val_if_fail (GST_IS_BUFFER (buffer), FALSE);
1175   g_return_val_if_fail (info != NULL, FALSE);
1176   len = GST_BUFFER_MEM_LEN (buffer);
1177   g_return_val_if_fail ((len == 0 && idx == 0 && length == -1) ||
1178       (length == -1 && idx < len) || (length > 0
1179           && length + idx <= len), FALSE);
1180
1181   write = (flags & GST_MAP_WRITE) != 0;
1182   writable = gst_buffer_is_writable (buffer);
1183
1184   /* check if we can write when asked for write access */
1185   if (G_UNLIKELY (write && !writable))
1186     goto not_writable;
1187
1188   if (length == -1)
1189     length = len - idx;
1190
1191   mem = _get_merged_memory (buffer, idx, length);
1192   if (G_UNLIKELY (mem == NULL))
1193     goto no_memory;
1194
1195   /* now try to map */
1196   nmem = gst_memory_make_mapped (mem, info, flags);
1197   if (G_UNLIKELY (nmem == NULL))
1198     goto cannot_map;
1199
1200   /* if we merged or when the map returned a different memory, we try to replace
1201    * the memory in the buffer */
1202   if (G_UNLIKELY (length > 1 || nmem != mem)) {
1203     /* if the buffer is writable, replace the memory */
1204     if (writable) {
1205       _replace_memory (buffer, len, idx, length, gst_memory_ref (nmem));
1206     } else {
1207       if (len > 1) {
1208         GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
1209             "temporary mapping for memory %p in buffer %p", nmem, buffer);
1210       }
1211     }
1212   }
1213   return TRUE;
1214
1215   /* ERROR */
1216 not_writable:
1217   {
1218     GST_WARNING_OBJECT (buffer, "write map requested on non-writable buffer");
1219     g_critical ("write map requested on non-writable buffer");
1220     return FALSE;
1221   }
1222 no_memory:
1223   {
1224     /* empty buffer, we need to return NULL */
1225     GST_DEBUG_OBJECT (buffer, "can't get buffer memory");
1226     info->memory = NULL;
1227     info->data = NULL;
1228     info->size = 0;
1229     info->maxsize = 0;
1230     return TRUE;
1231   }
1232 cannot_map:
1233   {
1234     GST_DEBUG_OBJECT (buffer, "cannot map memory");
1235     return FALSE;
1236   }
1237 }
1238
1239 /**
1240  * gst_buffer_unmap:
1241  * @buffer: a #GstBuffer.
1242  * @info: a #GstMapInfo
1243  *
1244  * Release the memory previously mapped with gst_buffer_map().
1245  */
1246 void
1247 gst_buffer_unmap (GstBuffer * buffer, GstMapInfo * info)
1248 {
1249   g_return_if_fail (GST_IS_BUFFER (buffer));
1250   g_return_if_fail (info != NULL);
1251
1252   /* we need to check for NULL, it is possible that we tried to map a buffer
1253    * without memory and we should be able to unmap that fine */
1254   if (G_LIKELY (info->memory)) {
1255     gst_memory_unmap (info->memory, info);
1256     gst_memory_unref (info->memory);
1257   }
1258 }
1259
1260 /**
1261  * gst_buffer_fill:
1262  * @buffer: a #GstBuffer.
1263  * @offset: the offset to fill
1264  * @src: the source address
1265  * @size: the size to fill
1266  *
1267  * Copy @size bytes from @src to @buffer at @offset.
1268  *
1269  * Returns: The amount of bytes copied. This value can be lower than @size
1270  *    when @buffer did not contain enough data.
1271  */
1272 gsize
1273 gst_buffer_fill (GstBuffer * buffer, gsize offset, gconstpointer src,
1274     gsize size)
1275 {
1276   gsize i, len, left;
1277   const guint8 *ptr = src;
1278
1279   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
1280   g_return_val_if_fail (gst_buffer_is_writable (buffer), 0);
1281   g_return_val_if_fail (src != NULL, 0);
1282
1283   len = GST_BUFFER_MEM_LEN (buffer);
1284   left = size;
1285
1286   for (i = 0; i < len && left > 0; i++) {
1287     GstMapInfo info;
1288     gsize tocopy;
1289     GstMemory *mem;
1290
1291     mem = _get_mapped (buffer, i, &info, GST_MAP_WRITE);
1292     if (info.size > offset) {
1293       /* we have enough */
1294       tocopy = MIN (info.size - offset, left);
1295       memcpy ((guint8 *) info.data + offset, ptr, tocopy);
1296       left -= tocopy;
1297       ptr += tocopy;
1298       offset = 0;
1299     } else {
1300       /* offset past buffer, skip */
1301       offset -= info.size;
1302     }
1303     gst_memory_unmap (mem, &info);
1304   }
1305   return size - left;
1306 }
1307
1308 /**
1309  * gst_buffer_extract:
1310  * @buffer: a #GstBuffer.
1311  * @offset: the offset to extract
1312  * @dest: the destination address
1313  * @size: the size to extract
1314  *
1315  * Copy @size bytes starting from @offset in @buffer to @dest.
1316  *
1317  * Returns: The amount of bytes extracted. This value can be lower than @size
1318  *    when @buffer did not contain enough data.
1319  */
1320 gsize
1321 gst_buffer_extract (GstBuffer * buffer, gsize offset, gpointer dest, gsize size)
1322 {
1323   gsize i, len, left;
1324   guint8 *ptr = dest;
1325
1326   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
1327   g_return_val_if_fail (dest != NULL, 0);
1328
1329   len = GST_BUFFER_MEM_LEN (buffer);
1330   left = size;
1331
1332   for (i = 0; i < len && left > 0; i++) {
1333     GstMapInfo info;
1334     gsize tocopy;
1335     GstMemory *mem;
1336
1337     mem = _get_mapped (buffer, i, &info, GST_MAP_READ);
1338     if (info.size > offset) {
1339       /* we have enough */
1340       tocopy = MIN (info.size - offset, left);
1341       memcpy (ptr, (guint8 *) info.data + offset, tocopy);
1342       left -= tocopy;
1343       ptr += tocopy;
1344       offset = 0;
1345     } else {
1346       /* offset past buffer, skip */
1347       offset -= info.size;
1348     }
1349     gst_memory_unmap (mem, &info);
1350   }
1351   return size - left;
1352 }
1353
1354 /**
1355  * gst_buffer_memcmp:
1356  * @buffer: a #GstBuffer.
1357  * @offset: the offset in @buffer
1358  * @mem: the memory to compare
1359  * @size: the size to compare
1360  *
1361  * Compare @size bytes starting from @offset in @buffer with the memory in @mem.
1362  *
1363  * Returns: 0 if the memory is equal.
1364  */
1365 gint
1366 gst_buffer_memcmp (GstBuffer * buffer, gsize offset, gconstpointer mem,
1367     gsize size)
1368 {
1369   gsize i, len;
1370   const guint8 *ptr = mem;
1371   gint res = 0;
1372
1373   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
1374   g_return_val_if_fail (mem != NULL, 0);
1375
1376   len = GST_BUFFER_MEM_LEN (buffer);
1377
1378   for (i = 0; i < len && size > 0 && res == 0; i++) {
1379     GstMapInfo info;
1380     gsize tocmp;
1381     GstMemory *mem;
1382
1383     mem = _get_mapped (buffer, i, &info, GST_MAP_READ);
1384     if (info.size > offset) {
1385       /* we have enough */
1386       tocmp = MIN (info.size - offset, size);
1387       res = memcmp (ptr, (guint8 *) info.data + offset, tocmp);
1388       size -= tocmp;
1389       ptr += tocmp;
1390       offset = 0;
1391     } else {
1392       /* offset past buffer, skip */
1393       offset -= info.size;
1394     }
1395     gst_memory_unmap (mem, &info);
1396   }
1397   return res;
1398 }
1399
1400 /**
1401  * gst_buffer_memset:
1402  * @buffer: a #GstBuffer.
1403  * @offset: the offset in @buffer
1404  * @val: the value to set
1405  * @size: the size to set
1406  *
1407  * Fill @buf with @size bytes with @val starting from @offset.
1408  *
1409  * Returns: The amount of bytes filled. This value can be lower than @size
1410  *    when @buffer did not contain enough data.
1411  */
1412 gsize
1413 gst_buffer_memset (GstBuffer * buffer, gsize offset, guint8 val, gsize size)
1414 {
1415   gsize i, len, left;
1416
1417   g_return_val_if_fail (GST_IS_BUFFER (buffer), 0);
1418   g_return_val_if_fail (gst_buffer_is_writable (buffer), 0);
1419
1420   len = GST_BUFFER_MEM_LEN (buffer);
1421   left = size;
1422
1423   for (i = 0; i < len && left > 0; i++) {
1424     GstMapInfo info;
1425     gsize toset;
1426     GstMemory *mem;
1427
1428     mem = _get_mapped (buffer, i, &info, GST_MAP_WRITE);
1429     if (info.size > offset) {
1430       /* we have enough */
1431       toset = MIN (info.size - offset, left);
1432       memset ((guint8 *) info.data + offset, val, toset);
1433       left -= toset;
1434       offset = 0;
1435     } else {
1436       /* offset past buffer, skip */
1437       offset -= info.size;
1438     }
1439     gst_memory_unmap (mem, &info);
1440   }
1441   return size - left;
1442 }
1443
1444 /**
1445  * gst_buffer_copy_region:
1446  * @parent: a #GstBuffer.
1447  * @flags: the #GstBufferCopyFlags
1448  * @offset: the offset into parent #GstBuffer at which the new sub-buffer
1449  *          begins.
1450  * @size: the size of the new #GstBuffer sub-buffer, in bytes.
1451  *
1452  * Creates a sub-buffer from @parent at @offset and @size.
1453  * This sub-buffer uses the actual memory space of the parent buffer.
1454  * This function will copy the offset and timestamp fields when the
1455  * offset is 0. If not, they will be set to #GST_CLOCK_TIME_NONE and
1456  * #GST_BUFFER_OFFSET_NONE.
1457  * If @offset equals 0 and @size equals the total size of @buffer, the
1458  * duration and offset end fields are also copied. If not they will be set
1459  * to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE.
1460  *
1461  * MT safe.
1462  *
1463  * Returns: (transfer full): the new #GstBuffer or NULL if the arguments were
1464  *     invalid.
1465  */
1466 GstBuffer *
1467 gst_buffer_copy_region (GstBuffer * buffer, GstBufferCopyFlags flags,
1468     gsize offset, gsize size)
1469 {
1470   GstBuffer *copy;
1471
1472   g_return_val_if_fail (buffer != NULL, NULL);
1473
1474   /* create the new buffer */
1475   copy = gst_buffer_new ();
1476
1477   GST_CAT_LOG (GST_CAT_BUFFER, "new region copy %p of %p %" G_GSIZE_FORMAT
1478       "-%" G_GSIZE_FORMAT, copy, buffer, offset, size);
1479
1480   gst_buffer_copy_into (copy, buffer, flags, offset, size);
1481
1482   return copy;
1483 }
1484
1485 /**
1486  * gst_buffer_append:
1487  * @buf1: (transfer full): the first source #GstBuffer to append.
1488  * @buf2: (transfer full): the second source #GstBuffer to append.
1489  *
1490  * Append all the memory from @buf2 to @buf1. The result buffer will contain a
1491  * concatenation of the memory of @buf1 and @buf2.
1492  *
1493  * Returns: (transfer full): the new #GstBuffer that contains the memory
1494  *     of the two source buffers.
1495  */
1496 GstBuffer *
1497 gst_buffer_append (GstBuffer * buf1, GstBuffer * buf2)
1498 {
1499   gsize i, len;
1500
1501   g_return_val_if_fail (GST_IS_BUFFER (buf1), NULL);
1502   g_return_val_if_fail (GST_IS_BUFFER (buf2), NULL);
1503
1504   buf1 = gst_buffer_make_writable (buf1);
1505   buf2 = gst_buffer_make_writable (buf2);
1506
1507   len = GST_BUFFER_MEM_LEN (buf2);
1508   for (i = 0; i < len; i++) {
1509     GstMemory *mem;
1510
1511     mem = GST_BUFFER_MEM_PTR (buf2, i);
1512     GST_BUFFER_MEM_PTR (buf2, i) = NULL;
1513     _memory_add (buf1, -1, mem);
1514   }
1515
1516   /* we can calculate the duration too. Also make sure we're not messing
1517    * with invalid DURATIONS */
1518   if (GST_BUFFER_DURATION_IS_VALID (buf1) &&
1519       GST_BUFFER_DURATION_IS_VALID (buf2)) {
1520     /* add duration */
1521     GST_BUFFER_DURATION (buf1) += GST_BUFFER_DURATION (buf2);
1522   }
1523   if (GST_BUFFER_OFFSET_END_IS_VALID (buf2)) {
1524     /* set offset_end */
1525     GST_BUFFER_OFFSET_END (buf1) = GST_BUFFER_OFFSET_END (buf2);
1526   }
1527
1528   GST_BUFFER_MEM_LEN (buf2) = 0;
1529   gst_buffer_unref (buf2);
1530
1531   return buf1;
1532 }
1533
1534 /**
1535  * gst_buffer_get_meta:
1536  * @buffer: a #GstBuffer
1537  * @api: the #GType of an API
1538  *
1539  * Get the metadata for @api on buffer. When there is no such
1540  * metadata, NULL is returned.
1541  *
1542  * Returns: the metadata for @api on @buffer.
1543  */
1544 GstMeta *
1545 gst_buffer_get_meta (GstBuffer * buffer, GType api)
1546 {
1547   GstMetaItem *item;
1548   GstMeta *result = NULL;
1549
1550   g_return_val_if_fail (buffer != NULL, NULL);
1551   g_return_val_if_fail (api != 0, NULL);
1552
1553   /* find GstMeta of the requested API */
1554   for (item = GST_BUFFER_META (buffer); item; item = item->next) {
1555     GstMeta *meta = &item->meta;
1556     if (meta->info->api == api) {
1557       result = meta;
1558       break;
1559     }
1560   }
1561   return result;
1562 }
1563
1564 /**
1565  * gst_buffer_add_meta:
1566  * @buffer: a #GstBuffer
1567  * @info: a #GstMetaInfo
1568  * @params: params for @info
1569  *
1570  * Add metadata for @info to @buffer using the parameters in @params.
1571  *
1572  * Returns: (transfer none): the metadata for the api in @info on @buffer.
1573  */
1574 GstMeta *
1575 gst_buffer_add_meta (GstBuffer * buffer, const GstMetaInfo * info,
1576     gpointer params)
1577 {
1578   GstMetaItem *item;
1579   GstMeta *result = NULL;
1580   gsize size;
1581
1582   g_return_val_if_fail (buffer != NULL, NULL);
1583   g_return_val_if_fail (info != NULL, NULL);
1584   g_return_val_if_fail (gst_buffer_is_writable (buffer), NULL);
1585
1586   /* create a new slice */
1587   size = ITEM_SIZE (info);
1588   item = g_slice_alloc (size);
1589   result = &item->meta;
1590   result->info = info;
1591   result->flags = GST_META_FLAG_NONE;
1592
1593   GST_CAT_DEBUG (GST_CAT_BUFFER,
1594       "alloc metadata %p (%s) of size %" G_GSIZE_FORMAT, result,
1595       g_type_name (info->type), info->size);
1596
1597   /* call the init_func when needed */
1598   if (info->init_func)
1599     if (!info->init_func (result, params, buffer))
1600       goto init_failed;
1601
1602   /* and add to the list of metadata */
1603   item->next = GST_BUFFER_META (buffer);
1604   GST_BUFFER_META (buffer) = item;
1605
1606   return result;
1607
1608 init_failed:
1609   {
1610     g_slice_free1 (size, item);
1611     return NULL;
1612   }
1613 }
1614
1615 /**
1616  * gst_buffer_remove_meta:
1617  * @buffer: a #GstBuffer
1618  * @meta: a #GstMeta
1619  *
1620  * Remove the metadata for @meta on @buffer.
1621  *
1622  * Returns: %TRUE if the metadata existed and was removed, %FALSE if no such
1623  * metadata was on @buffer.
1624  */
1625 gboolean
1626 gst_buffer_remove_meta (GstBuffer * buffer, GstMeta * meta)
1627 {
1628   GstMetaItem *walk, *prev;
1629
1630   g_return_val_if_fail (buffer != NULL, FALSE);
1631   g_return_val_if_fail (meta != NULL, FALSE);
1632   g_return_val_if_fail (gst_buffer_is_writable (buffer), FALSE);
1633   g_return_val_if_fail (!GST_META_FLAG_IS_SET (meta, GST_META_FLAG_LOCKED),
1634       FALSE);
1635
1636   /* find the metadata and delete */
1637   prev = GST_BUFFER_META (buffer);
1638   for (walk = prev; walk; walk = walk->next) {
1639     GstMeta *m = &walk->meta;
1640     if (m == meta) {
1641       const GstMetaInfo *info = meta->info;
1642
1643       /* remove from list */
1644       if (GST_BUFFER_META (buffer) == walk)
1645         GST_BUFFER_META (buffer) = walk->next;
1646       else
1647         prev->next = walk->next;
1648       /* call free_func if any */
1649       if (info->free_func)
1650         info->free_func (m, buffer);
1651
1652       /* and free the slice */
1653       g_slice_free1 (ITEM_SIZE (info), walk);
1654       break;
1655     }
1656     prev = walk;
1657   }
1658   return walk != NULL;
1659 }
1660
1661 /**
1662  * gst_buffer_iterate_meta:
1663  * @buffer: a #GstBuffer
1664  * @state: an opaque state pointer
1665  *
1666  * Retrieve the next #GstMeta after @current. If @state points
1667  * to %NULL, the first metadata is returned.
1668  *
1669  * @state will be updated with an opage state pointer
1670  *
1671  * Returns: The next #GstMeta or %NULL when there are no more items.
1672  */
1673 GstMeta *
1674 gst_buffer_iterate_meta (GstBuffer * buffer, gpointer * state)
1675 {
1676   GstMetaItem **meta;
1677
1678   g_return_val_if_fail (buffer != NULL, NULL);
1679   g_return_val_if_fail (state != NULL, NULL);
1680
1681   meta = (GstMetaItem **) state;
1682   if (*meta == NULL)
1683     /* state NULL, move to first item */
1684     *meta = GST_BUFFER_META (buffer);
1685   else
1686     /* state !NULL, move to next item in list */
1687     *meta = (*meta)->next;
1688
1689   if (*meta)
1690     return &(*meta)->meta;
1691   else
1692     return NULL;
1693 }
1694
1695 /**
1696  * gst_buffer_foreach_meta:
1697  * @buffer: a #GstBuffer
1698  * @func: (scope call): a #GstBufferForeachMetaFunc to call
1699  * @user_data: (closure): user data passed to @func
1700  *
1701  * Call @func with @user_data for each meta in @buffer.
1702  *
1703  * @func can modify the passed meta pointer or its contents. The return value
1704  * of @func define if this function returns or if the remaining metadata items
1705  * in the buffer should be skipped.
1706  */
1707 void
1708 gst_buffer_foreach_meta (GstBuffer * buffer, GstBufferForeachMetaFunc func,
1709     gpointer user_data)
1710 {
1711   GstMetaItem *walk, *prev, *next;
1712
1713   g_return_if_fail (buffer != NULL);
1714   g_return_if_fail (func != NULL);
1715
1716   /* find the metadata and delete */
1717   prev = GST_BUFFER_META (buffer);
1718   for (walk = prev; walk; walk = next) {
1719     GstMeta *m, *new;
1720     gboolean res;
1721
1722     m = new = &walk->meta;
1723     next = walk->next;
1724
1725     res = func (buffer, &new, user_data);
1726
1727     if (new == NULL) {
1728       const GstMetaInfo *info = m->info;
1729
1730       GST_CAT_DEBUG (GST_CAT_BUFFER, "remove metadata %p (%s)", m,
1731           g_type_name (info->type));
1732
1733       g_return_if_fail (gst_buffer_is_writable (buffer));
1734       g_return_if_fail (!GST_META_FLAG_IS_SET (m, GST_META_FLAG_LOCKED));
1735
1736       /* remove from list */
1737       if (GST_BUFFER_META (buffer) == walk)
1738         GST_BUFFER_META (buffer) = next;
1739       else
1740         prev->next = next;
1741
1742       /* call free_func if any */
1743       if (info->free_func)
1744         info->free_func (m, buffer);
1745
1746       /* and free the slice */
1747       g_slice_free1 (ITEM_SIZE (info), walk);
1748     }
1749     if (!res)
1750       break;
1751   }
1752 }