gst/gstmemory.c

   1 /* GStreamer
   2  * Copyright (C) 2011 Wim Taymans <wim.taymans@gmail.be>
   3  *
   4  * gstmemory.c: memory block handling
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /**
  23  * SECTION:gstmemory
  24  * @short_description: refcounted wrapper for memory blocks
  25  * @see_also: #GstBuffer
  26  *
  27  * GstMemory is a lightweight refcounted object that wraps a region of memory.
  28  * They are typically used to manage the data of a #GstBuffer.
  29  *
  30  * A GstMemory object has an allocated region of memory of maxsize. The maximum
  31  * size does not change during the lifetime of the memory object. The memory
  32  * also has an offset and size property that specifies the valid range of memory
  33  * in the allocated region.
  34  *
  35  * Memory is usually created by allocators with a gst_allocator_alloc()
  36  * method call. When NULL is used as the allocator, the default allocator will
  37  * be used.
  38  *
  39  * New allocators can be registered with gst_allocator_register().
  40  * Allocators are identified by name and can be retrieved with
  41  * gst_allocator_find(). gst_allocator_set_default() can be used to change the
  42  * default allocator.
  43  *
  44  * New memory can be created with gst_memory_new_wrapped() that wraps the memory
  45  * allocated elsewhere.
  46  *
  47  * Refcounting of the memory block is performed with gst_memory_ref() and
  48  * gst_memory_unref().
  49  *
  50  * The size of the memory can be retrieved and changed with
  51  * gst_memory_get_sizes() and gst_memory_resize() respectively.
  52  *
  53  * Getting access to the data of the memory is performed with gst_memory_map().
  54  * The call will return a pointer to offset bytes into the region of memory.
  55  * After the memory access is completed, gst_memory_unmap() should be called.
  56  *
  57  * Memory can be copied with gst_memory_copy(), which will return a writable
  58  * copy. gst_memory_share() will create a new memory block that shares the
  59  * memory with an existing memory block at a custom offset and with a custom
  60  * size.
  61  *
  62  * Memory can be efficiently merged when gst_memory_is_span() returns TRUE.
  63  *
  64  * Last reviewed on 2012-03-28 (0.11.3)
  65  */
  66
  67 #ifdef HAVE_CONFIG_H
  68 #include "config.h"
  69 #endif
  70
  71 #include "gst_private.h"
  72 #include "gstmemory.h"
  73
  74 GST_DEFINE_MINI_OBJECT_TYPE (GstMemory, gst_memory);
  75
  76 GST_DEFINE_MINI_OBJECT_TYPE (GstAllocator, gst_allocator);
  77
  78 G_DEFINE_BOXED_TYPE (GstAllocationParams, gst_allocation_params,
  79     (GBoxedCopyFunc) gst_allocation_params_copy,
  80     (GBoxedFreeFunc) gst_allocation_params_free);
  81
  82 #if defined(MEMORY_ALIGNMENT_MALLOC)
  83 size_t gst_memory_alignment = 7;
  84 #elif defined(MEMORY_ALIGNMENT_PAGESIZE)
  85 /* we fill this in in the _init method */
  86 size_t gst_memory_alignment = 0;
  87 #elif defined(MEMORY_ALIGNMENT)
  88 size_t gst_memory_alignment = MEMORY_ALIGNMENT - 1;
  89 #else
  90 #error "No memory alignment configured"
  91 size_t gst_memory_alignment = 0;
  92 #endif
  93
  94 struct _GstAllocator
  95 {
  96   GstMiniObject mini_object;
  97
  98   gsize slice_size;
  99
 100   GstMemoryInfo info;
 101
 102   gpointer user_data;
 103   GDestroyNotify notify;
 104 };
 105
 106 /* default memory implementation */
 107 typedef struct
 108 {
 109   GstMemory mem;
 110   gsize slice_size;
 111   guint8 *data;
 112   gpointer user_data;
 113   GDestroyNotify notify;
 114 } GstMemoryDefault;
 115
 116 /* the default allocator */
 117 static GstAllocator *_default_allocator;
 118
 119 /* our predefined allocators */
 120 static GstAllocator *_default_mem_impl;
 121
 122 static GstMemory *
 123 _gst_memory_copy (GstMemory * mem)
 124 {
 125   return gst_memory_copy (mem, 0, -1);
 126 }
 127
 128 static void
 129 _gst_memory_free (GstMemory * mem)
 130 {
 131   /* there should be no outstanding mappings */
 132   g_return_if_fail (g_atomic_int_get (&mem->state) < 4);
 133   mem->allocator->info.mem_free (mem);
 134 }
 135
 136 /* initialize the fields */
 137 static void
 138 _default_mem_init (GstMemoryDefault * mem, GstMemoryFlags flags,
 139     GstMemory * parent, gsize slice_size, gpointer data,
 140     gsize maxsize, gsize offset, gsize size, gsize align,
 141     gpointer user_data, GDestroyNotify notify)
 142 {
 143   gst_mini_object_init (GST_MINI_OBJECT_CAST (mem), GST_TYPE_MEMORY);
 144
 145   mem->mem.mini_object.copy = (GstMiniObjectCopyFunction) _gst_memory_copy;
 146   mem->mem.mini_object.dispose = NULL;
 147   mem->mem.mini_object.free = (GstMiniObjectFreeFunction) _gst_memory_free;
 148   mem->mem.mini_object.flags = flags;
 149
 150   mem->mem.allocator = _default_mem_impl;
 151   mem->mem.parent = parent ? gst_memory_ref (parent) : NULL;
 152   mem->mem.state = (flags & GST_MEMORY_FLAG_READONLY ? 0x1 : 0);
 153   mem->mem.maxsize = maxsize;
 154   mem->mem.align = align;
 155   mem->mem.offset = offset;
 156   mem->mem.size = size;
 157   mem->slice_size = slice_size;
 158   mem->data = data;
 159   mem->user_data = user_data;
 160   mem->notify = notify;
 161
 162   GST_CAT_DEBUG (GST_CAT_MEMORY, "new memory %p, maxsize:%" G_GSIZE_FORMAT
 163       " offset:%" G_GSIZE_FORMAT " size:%" G_GSIZE_FORMAT, mem, maxsize,
 164       offset, size);
 165 }
 166
 167 /* create a new memory block that manages the given memory */
 168 static GstMemoryDefault *
 169 _default_mem_new (GstMemoryFlags flags, GstMemory * parent, gpointer data,
 170     gsize maxsize, gsize offset, gsize size, gsize align, gpointer user_data,
 171     GDestroyNotify notify)
 172 {
 173   GstMemoryDefault *mem;
 174   gsize slice_size;
 175
 176   slice_size = sizeof (GstMemoryDefault);
 177
 178   mem = g_slice_alloc (slice_size);
 179   _default_mem_init (mem, flags, parent, slice_size,
 180       data, maxsize, offset, size, align, user_data, notify);
 181
 182   return mem;
 183 }
 184
 185 /* allocate the memory and structure in one block */
 186 static GstMemoryDefault *
 187 _default_mem_new_block (GstMemoryFlags flags, gsize maxsize, gsize align,
 188     gsize offset, gsize size)
 189 {
 190   GstMemoryDefault *mem;
 191   gsize aoffset, slice_size, padding;
 192   guint8 *data;
 193
 194   /* ensure configured alignment */
 195   align |= gst_memory_alignment;
 196   /* allocate more to compensate for alignment */
 197   maxsize += align;
 198   /* alloc header and data in one block */
 199   slice_size = sizeof (GstMemoryDefault) + maxsize;
 200
 201   mem = g_slice_alloc (slice_size);
 202   if (mem == NULL)
 203     return NULL;
 204
 205   data = (guint8 *) mem + sizeof (GstMemoryDefault);
 206
 207   /* do alignment */
 208   if ((aoffset = ((guintptr) data & align))) {
 209     aoffset = (align + 1) - aoffset;
 210     data += aoffset;
 211     maxsize -= aoffset;
 212   }
 213
 214   if (offset && (flags & GST_MEMORY_FLAG_ZERO_PREFIXED))
 215     memset (data, 0, offset);
 216
 217   padding = maxsize - (offset + size);
 218   if (padding && (flags & GST_MEMORY_FLAG_ZERO_PADDED))
 219     memset (data + offset + size, 0, padding);
 220
 221   _default_mem_init (mem, flags, NULL, slice_size, data, maxsize,
 222       offset, size, align, NULL, NULL);
 223
 224   return mem;
 225 }
 226
 227 static GstMemory *
 228 _default_alloc_alloc (GstAllocator * allocator, gsize size,
 229     GstAllocationParams * params, gpointer user_data)
 230 {
 231   gsize maxsize = size + params->prefix + params->padding;
 232
 233   return (GstMemory *) _default_mem_new_block (params->flags,
 234       maxsize, params->align, params->prefix, size);
 235 }
 236
 237 static gpointer
 238 _default_mem_map (GstMemoryDefault * mem, gsize maxsize, GstMapFlags flags)
 239 {
 240   return mem->data;
 241 }
 242
 243 static gboolean
 244 _default_mem_unmap (GstMemoryDefault * mem)
 245 {
 246   return TRUE;
 247 }
 248
 249 static void
 250 _default_mem_free (GstMemoryDefault * mem)
 251 {
 252   GST_CAT_DEBUG (GST_CAT_MEMORY, "free memory %p", mem);
 253
 254   if (mem->mem.parent)
 255     gst_memory_unref (mem->mem.parent);
 256
 257   if (mem->notify)
 258     mem->notify (mem->user_data);
 259
 260   g_slice_free1 (mem->slice_size, mem);
 261 }
 262
 263 static GstMemoryDefault *
 264 _default_mem_copy (GstMemoryDefault * mem, gssize offset, gsize size)
 265 {
 266   GstMemoryDefault *copy;
 267
 268   if (size == -1)
 269     size = mem->mem.size > offset ? mem->mem.size - offset : 0;
 270
 271   copy =
 272       _default_mem_new_block (0, mem->mem.maxsize, 0, mem->mem.offset + offset,
 273       size);
 274   GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
 275       "memcpy %" G_GSIZE_FORMAT " memory %p -> %p", mem->mem.maxsize, mem,
 276       copy);
 277   memcpy (copy->data, mem->data, mem->mem.maxsize);
 278
 279   return copy;
 280 }
 281
 282 static GstMemoryDefault *
 283 _default_mem_share (GstMemoryDefault * mem, gssize offset, gsize size)
 284 {
 285   GstMemoryDefault *sub;
 286   GstMemory *parent;
 287
 288   /* find the real parent */
 289   if ((parent = mem->mem.parent) == NULL)
 290     parent = (GstMemory *) mem;
 291
 292   if (size == -1)
 293     size = mem->mem.size - offset;
 294
 295   sub =
 296       _default_mem_new (GST_MINI_OBJECT_FLAGS (parent), parent, mem->data,
 297       mem->mem.maxsize, mem->mem.offset + offset, size, mem->mem.align, NULL,
 298       NULL);
 299
 300   return sub;
 301 }
 302
 303 static gboolean
 304 _default_mem_is_span (GstMemoryDefault * mem1, GstMemoryDefault * mem2,
 305     gsize * offset)
 306 {
 307
 308   if (offset) {
 309     GstMemoryDefault *parent;
 310
 311     parent = (GstMemoryDefault *) mem1->mem.parent;
 312
 313     *offset = mem1->mem.offset - parent->mem.offset;
 314   }
 315
 316   /* and memory is contiguous */
 317   return mem1->data + mem1->mem.offset + mem1->mem.size ==
 318       mem2->data + mem2->mem.offset;
 319 }
 320
 321 static GstMemory *
 322 _fallback_mem_copy (GstMemory * mem, gssize offset, gssize size)
 323 {
 324   GstMemory *copy;
 325   GstMapInfo sinfo, dinfo;
 326   GstAllocationParams params = { 0, 0, 0, mem->align, };
 327
 328   if (!gst_memory_map (mem, &sinfo, GST_MAP_READ))
 329     return NULL;
 330
 331   if (size == -1)
 332     size = sinfo.size > offset ? sinfo.size - offset : 0;
 333
 334   /* use the same allocator as the memory we copy  */
 335   copy = gst_allocator_alloc (mem->allocator, size, &params);
 336   if (!gst_memory_map (copy, &dinfo, GST_MAP_WRITE)) {
 337     GST_CAT_WARNING (GST_CAT_MEMORY, "could not write map memory %p", copy);
 338     gst_memory_unmap (mem, &sinfo);
 339     return NULL;
 340   }
 341
 342   GST_CAT_DEBUG (GST_CAT_PERFORMANCE,
 343       "memcpy %" G_GSSIZE_FORMAT " memory %p -> %p", size, mem, copy);
 344   memcpy (dinfo.data, sinfo.data + offset, size);
 345   gst_memory_unmap (copy, &dinfo);
 346   gst_memory_unmap (mem, &sinfo);
 347
 348   return copy;
 349 }
 350
 351 static gboolean
 352 _fallback_mem_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
 353 {
 354   return FALSE;
 355 }
 356
 357 static GRWLock lock;
 358 static GHashTable *allocators;
 359
 360 static void
 361 _priv_sysmem_notify (gpointer user_data)
 362 {
 363   g_warning ("The default memory allocator was freed!");
 364 }
 365
 366 void
 367 _priv_gst_memory_initialize (void)
 368 {
 369   static const GstMemoryInfo _mem_info = {
 370     GST_ALLOCATOR_SYSMEM,
 371     (GstAllocatorAllocFunction) _default_alloc_alloc,
 372     (GstMemoryMapFunction) _default_mem_map,
 373     (GstMemoryUnmapFunction) _default_mem_unmap,
 374     (GstMemoryFreeFunction) _default_mem_free,
 375     (GstMemoryCopyFunction) _default_mem_copy,
 376     (GstMemoryShareFunction) _default_mem_share,
 377     (GstMemoryIsSpanFunction) _default_mem_is_span,
 378   };
 379
 380   g_rw_lock_init (&lock);
 381   allocators = g_hash_table_new (g_str_hash, g_str_equal);
 382
 383 #ifdef HAVE_GETPAGESIZE
 384 #ifdef MEMORY_ALIGNMENT_PAGESIZE
 385   gst_memory_alignment = getpagesize () - 1;
 386 #endif
 387 #endif
 388
 389   GST_CAT_DEBUG (GST_CAT_MEMORY, "memory alignment: %" G_GSIZE_FORMAT,
 390       gst_memory_alignment);
 391
 392   _default_mem_impl = gst_allocator_new (&_mem_info, NULL, _priv_sysmem_notify);
 393
 394   _default_allocator = gst_allocator_ref (_default_mem_impl);
 395   gst_allocator_register (GST_ALLOCATOR_SYSMEM,
 396       gst_allocator_ref (_default_mem_impl));
 397 }
 398
 399 /**
 400  * gst_memory_new_wrapped:
 401  * @flags: #GstMemoryFlags
 402  * @data: data to wrap
 403  * @maxsize: allocated size of @data
 404  * @offset: offset in @data
 405  * @size: size of valid data
 406  * @user_data: user_data
 407  * @notify: called with @user_data when the memory is freed
 408  *
 409  * Allocate a new memory block that wraps the given @data.
 410  *
 411  * The prefix/padding must be filled with 0 if @flags contains
 412  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 413  *
 414  * Returns: a new #GstMemory.
 415  */
 416 GstMemory *
 417 gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
 418     gsize maxsize, gsize offset, gsize size, gpointer user_data,
 419     GDestroyNotify notify)
 420 {
 421   GstMemoryDefault *mem;
 422
 423   g_return_val_if_fail (data != NULL, NULL);
 424   g_return_val_if_fail (offset + size <= maxsize, NULL);
 425
 426   mem =
 427       _default_mem_new (flags, NULL, data, maxsize, offset, size, 0, user_data,
 428       notify);
 429
 430   return (GstMemory *) mem;
 431 }
 432
 433 /**
 434  * gst_memory_is_exclusive:
 435  * @mem: a #GstMemory
 436  *
 437  * Check if the current ref to @mem is exclusive, this means that no other
 438  * references exist other than @mem.
 439  */
 440 gboolean
 441 gst_memory_is_exclusive (GstMemory * mem)
 442 {
 443   g_return_val_if_fail (mem != NULL, FALSE);
 444
 445   return GST_MINI_OBJECT_REFCOUNT_VALUE (mem) == 1;
 446 }
 447
 448 /**
 449  * gst_memory_get_sizes:
 450  * @mem: a #GstMemory
 451  * @offset: pointer to offset
 452  * @maxsize: pointer to maxsize
 453  *
 454  * Get the current @size, @offset and @maxsize of @mem.
 455  *
 456  * Returns: the current sizes of @mem
 457  */
 458 gsize
 459 gst_memory_get_sizes (GstMemory * mem, gsize * offset, gsize * maxsize)
 460 {
 461   g_return_val_if_fail (mem != NULL, 0);
 462
 463   if (offset)
 464     *offset = mem->offset;
 465   if (maxsize)
 466     *maxsize = mem->maxsize;
 467
 468   return mem->size;
 469 }
 470
 471 /**
 472  * gst_memory_resize:
 473  * @mem: a #GstMemory
 474  * @offset: a new offset
 475  * @size: a new size
 476  *
 477  * Resize the memory region. @mem should be writable and offset + size should be
 478  * less than the maxsize of @mem.
 479  *
 480  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be
 481  * cleared when offset or padding is increased respectively.
 482  */
 483 void
 484 gst_memory_resize (GstMemory * mem, gssize offset, gsize size)
 485 {
 486   g_return_if_fail (mem != NULL);
 487   g_return_if_fail (offset >= 0 || mem->offset >= -offset);
 488   g_return_if_fail (size + mem->offset + offset <= mem->maxsize);
 489
 490   /* if we increase the prefix, we can't guarantee it is still 0 filled */
 491   if ((offset > 0) && GST_MEMORY_IS_ZERO_PREFIXED (mem))
 492     GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PREFIXED);
 493
 494   /* if we increase the padding, we can't guarantee it is still 0 filled */
 495   if ((offset + size < mem->size) && GST_MEMORY_IS_ZERO_PADDED (mem))
 496     GST_MEMORY_FLAG_UNSET (mem, GST_MEMORY_FLAG_ZERO_PADDED);
 497
 498   mem->offset += offset;
 499   mem->size = size;
 500 }
 501
 502 static gboolean
 503 gst_memory_lock (GstMemory * mem, GstMapFlags flags)
 504 {
 505   gint access_mode, state, newstate;
 506
 507   access_mode = flags & 3;
 508
 509   do {
 510     state = g_atomic_int_get (&mem->state);
 511     if (state == 0) {
 512       /* nothing mapped, set access_mode and refcount */
 513       newstate = 4 | access_mode;
 514     } else {
 515       /* access_mode must match */
 516       if ((state & access_mode) != access_mode)
 517         goto lock_failed;
 518       /* increase refcount */
 519       newstate = state + 4;
 520     }
 521   } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
 522
 523   return TRUE;
 524
 525 lock_failed:
 526   {
 527     GST_CAT_DEBUG (GST_CAT_MEMORY, "lock failed %p: state %d, access_mode %d",
 528         mem, state, access_mode);
 529     return FALSE;
 530   }
 531 }
 532
 533 static void
 534 gst_memory_unlock (GstMemory * mem)
 535 {
 536   gint state, newstate;
 537
 538   do {
 539     state = g_atomic_int_get (&mem->state);
 540     /* decrease the refcount */
 541     newstate = state - 4;
 542     /* last refcount, unset access_mode */
 543     if (newstate < 4)
 544       newstate = 0;
 545   } while (!g_atomic_int_compare_and_exchange (&mem->state, state, newstate));
 546 }
 547
 548
 549 /**
 550  * gst_memory_make_mapped:
 551  * @mem: (transfer full): a #GstMemory
 552  * @info: (out): pointer for info
 553  * @flags: mapping flags
 554  *
 555  * Create a #GstMemory object that is mapped with @flags. If @mem is mappable
 556  * with @flags, this function returns the mapped @mem directly. Otherwise a
 557  * mapped copy of @mem is returned.
 558  *
 559  * This function takes ownership of old @mem and returns a reference to a new
 560  * #GstMemory.
 561  *
 562  * Returns: (transfer full): a #GstMemory object mapped with @flags or NULL when
 563  * a mapping is not possible.
 564  */
 565 GstMemory *
 566 gst_memory_make_mapped (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
 567 {
 568   GstMemory *result;
 569
 570   if (gst_memory_map (mem, info, flags)) {
 571     result = mem;
 572   } else {
 573     result = gst_memory_copy (mem, 0, -1);
 574     gst_memory_unref (mem);
 575
 576     if (result == NULL)
 577       goto cannot_copy;
 578
 579     if (!gst_memory_map (result, info, flags))
 580       goto cannot_map;
 581   }
 582   return result;
 583
 584   /* ERRORS */
 585 cannot_copy:
 586   {
 587     GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot copy memory %p", mem);
 588     return NULL;
 589   }
 590 cannot_map:
 591   {
 592     GST_CAT_DEBUG (GST_CAT_MEMORY, "cannot map memory %p with flags %d", mem,
 593         flags);
 594     gst_memory_unref (result);
 595     return NULL;
 596   }
 597 }
 598
 599 /**
 600  * gst_memory_map:
 601  * @mem: a #GstMemory
 602  * @info: (out): pointer for info
 603  * @flags: mapping flags
 604  *
 605  * Fill @info with the pointer and sizes of the memory in @mem that can be
 606  * accessed according to @flags.
 607  *
 608  * This function can return %FALSE for various reasons:
 609  * - the memory backed by @mem is not accessible with the given @flags.
 610  * - the memory was already mapped with a different mapping.
 611  *
 612  * @info and its contents remain valid for as long as @mem is valid and
 613  * until gst_memory_unmap() is called.
 614  *
 615  * For each gst_memory_map() call, a corresponding gst_memory_unmap() call
 616  * should be done.
 617  *
 618  * Returns: %TRUE if the map operation was successful.
 619  */
 620 gboolean
 621 gst_memory_map (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)
 622 {
 623   g_return_val_if_fail (mem != NULL, FALSE);
 624   g_return_val_if_fail (info != NULL, FALSE);
 625
 626   if (!gst_memory_lock (mem, flags))
 627     goto lock_failed;
 628
 629   info->data = mem->allocator->info.mem_map (mem, mem->maxsize, flags);
 630
 631   if (G_UNLIKELY (info->data == NULL))
 632     goto error;
 633
 634   info->memory = mem;
 635   info->flags = flags;
 636   info->size = mem->size;
 637   info->maxsize = mem->maxsize - mem->offset;
 638   info->data = info->data + mem->offset;
 639
 640   return TRUE;
 641
 642   /* ERRORS */
 643 lock_failed:
 644   {
 645     GST_CAT_DEBUG (GST_CAT_MEMORY, "mem %p: lock %d failed", mem, flags);
 646     return FALSE;
 647   }
 648 error:
 649   {
 650     /* something went wrong, restore the orginal state again */
 651     GST_CAT_ERROR (GST_CAT_MEMORY, "mem %p: map failed", mem);
 652     gst_memory_unlock (mem);
 653     return FALSE;
 654   }
 655 }
 656
 657 /**
 658  * gst_memory_unmap:
 659  * @mem: a #GstMemory
 660  * @info: a #GstMapInfo
 661  *
 662  * Release the memory obtained with gst_memory_map()
 663  */
 664 void
 665 gst_memory_unmap (GstMemory * mem, GstMapInfo * info)
 666 {
 667   g_return_if_fail (mem != NULL);
 668   g_return_if_fail (info != NULL);
 669   g_return_if_fail (info->memory == mem);
 670   /* there must be a ref */
 671   g_return_if_fail (g_atomic_int_get (&mem->state) >= 4);
 672
 673   mem->allocator->info.mem_unmap (mem);
 674   gst_memory_unlock (mem);
 675 }
 676
 677 /**
 678  * gst_memory_copy:
 679  * @mem: a #GstMemory
 680  * @offset: an offset to copy
 681  * @size: size to copy or -1 to copy all bytes from offset
 682  *
 683  * Return a copy of @size bytes from @mem starting from @offset. This copy is
 684  * guaranteed to be writable. @size can be set to -1 to return a copy all bytes
 685  * from @offset.
 686  *
 687  * Returns: a new #GstMemory.
 688  */
 689 GstMemory *
 690 gst_memory_copy (GstMemory * mem, gssize offset, gssize size)
 691 {
 692   GstMemory *copy;
 693
 694   g_return_val_if_fail (mem != NULL, NULL);
 695
 696   copy = mem->allocator->info.mem_copy (mem, offset, size);
 697
 698   return copy;
 699 }
 700
 701 /**
 702  * gst_memory_share:
 703  * @mem: a #GstMemory
 704  * @offset: an offset to share
 705  * @size: size to share or -1 to share bytes from offset
 706  *
 707  * Return a shared copy of @size bytes from @mem starting from @offset. No
 708  * memory copy is performed and the memory region is simply shared. The result
 709  * is guaranteed to be not-writable. @size can be set to -1 to return a share
 710  * all bytes from @offset.
 711  *
 712  * Returns: a new #GstMemory.
 713  */
 714 GstMemory *
 715 gst_memory_share (GstMemory * mem, gssize offset, gssize size)
 716 {
 717   GstMemory *shared;
 718
 719   g_return_val_if_fail (mem != NULL, NULL);
 720   g_return_val_if_fail (!GST_MEMORY_FLAG_IS_SET (mem, GST_MEMORY_FLAG_NO_SHARE),
 721       NULL);
 722
 723   shared = mem->allocator->info.mem_share (mem, offset, size);
 724
 725   return shared;
 726 }
 727
 728 /**
 729  * gst_memory_is_span:
 730  * @mem1: a #GstMemory
 731  * @mem2: a #GstMemory
 732  * @offset: a pointer to a result offset
 733  *
 734  * Check if @mem1 and mem2 share the memory with a common parent memory object
 735  * and that the memory is contiguous.
 736  *
 737  * If this is the case, the memory of @mem1 and @mem2 can be merged
 738  * efficiently by performing gst_memory_share() on the parent object from
 739  * the returned @offset.
 740  *
 741  * Returns: %TRUE if the memory is contiguous and of a common parent.
 742  */
 743 gboolean
 744 gst_memory_is_span (GstMemory * mem1, GstMemory * mem2, gsize * offset)
 745 {
 746   g_return_val_if_fail (mem1 != NULL, FALSE);
 747   g_return_val_if_fail (mem2 != NULL, FALSE);
 748
 749   /* need to have the same allocators */
 750   if (mem1->allocator != mem2->allocator)
 751     return FALSE;
 752
 753   /* need to have the same parent */
 754   if (mem1->parent == NULL || mem1->parent != mem2->parent)
 755     return FALSE;
 756
 757   /* and memory is contiguous */
 758   if (!mem1->allocator->info.mem_is_span (mem1, mem2, offset))
 759     return FALSE;
 760
 761   return TRUE;
 762 }
 763
 764 static void
 765 _gst_allocator_free (GstAllocator * allocator)
 766 {
 767   if (allocator->notify)
 768     allocator->notify (allocator->user_data);
 769
 770   g_slice_free1 (allocator->slice_size, allocator);
 771 }
 772
 773 static GstAllocator *
 774 _gst_allocator_copy (GstAllocator * allocator)
 775 {
 776   return gst_allocator_ref (allocator);
 777 }
 778
 779 /**
 780  * gst_allocator_new:
 781  * @info: a #GstMemoryInfo
 782  * @user_data: user data
 783  * @notify: a #GDestroyNotify for @user_data
 784  *
 785  * Create a new memory allocator with @info and @user_data.
 786  *
 787  * All functions in @info are mandatory exept the copy and is_span
 788  * functions, which will have a default implementation when left NULL.
 789  *
 790  * The @user_data will be passed to all calls of the alloc function. @notify
 791  * will be called with @user_data when the allocator is freed.
 792  *
 793  * Returns: a new #GstAllocator.
 794  */
 795 GstAllocator *
 796 gst_allocator_new (const GstMemoryInfo * info, gpointer user_data,
 797     GDestroyNotify notify)
 798 {
 799   GstAllocator *allocator;
 800
 801   g_return_val_if_fail (info != NULL, NULL);
 802   g_return_val_if_fail (info->alloc != NULL, NULL);
 803   g_return_val_if_fail (info->mem_map != NULL, NULL);
 804   g_return_val_if_fail (info->mem_unmap != NULL, NULL);
 805   g_return_val_if_fail (info->mem_free != NULL, NULL);
 806   g_return_val_if_fail (info->mem_share != NULL, NULL);
 807
 808   allocator = g_slice_new0 (GstAllocator);
 809
 810   gst_mini_object_init (GST_MINI_OBJECT_CAST (allocator), GST_TYPE_ALLOCATOR);
 811
 812   allocator->mini_object.copy = (GstMiniObjectCopyFunction) _gst_allocator_copy;
 813   allocator->mini_object.free = (GstMiniObjectFreeFunction) _gst_allocator_free;
 814
 815   allocator->slice_size = sizeof (GstAllocator);
 816   allocator->info = *info;
 817   allocator->user_data = user_data;
 818   allocator->notify = notify;
 819
 820 #define INSTALL_FALLBACK(_t) \
 821   if (allocator->info._t == NULL) allocator->info._t = _fallback_ ##_t;
 822   INSTALL_FALLBACK (mem_copy);
 823   INSTALL_FALLBACK (mem_is_span);
 824 #undef INSTALL_FALLBACK
 825
 826   GST_CAT_DEBUG (GST_CAT_MEMORY, "new allocator %p", allocator);
 827
 828   return allocator;
 829 }
 830
 831 /**
 832  * gst_allocator_get_memory_type:
 833  * @allocator: a #GstAllocator
 834  *
 835  * Get the memory type allocated by this allocator
 836  *
 837  * Returns: the memory type provided by @allocator
 838  */
 839 const gchar *
 840 gst_allocator_get_memory_type (GstAllocator * allocator)
 841 {
 842   g_return_val_if_fail (allocator != NULL, NULL);
 843
 844   return allocator->info.mem_type;
 845 }
 846
 847 /**
 848  * gst_allocator_register:
 849  * @name: the name of the allocator
 850  * @allocator: (transfer full): #GstAllocator
 851  *
 852  * Registers the memory @allocator with @name. This function takes ownership of
 853  * @allocator.
 854  */
 855 void
 856 gst_allocator_register (const gchar * name, GstAllocator * allocator)
 857 {
 858   g_return_if_fail (name != NULL);
 859   g_return_if_fail (allocator != NULL);
 860
 861   GST_CAT_DEBUG (GST_CAT_MEMORY, "registering allocator %p with name \"%s\"",
 862       allocator, name);
 863
 864   g_rw_lock_writer_lock (&lock);
 865   g_hash_table_insert (allocators, (gpointer) name, (gpointer) allocator);
 866   g_rw_lock_writer_unlock (&lock);
 867 }
 868
 869 /**
 870  * gst_allocator_find:
 871  * @name: the name of the allocator
 872  *
 873  * Find a previously registered allocator with @name. When @name is NULL, the
 874  * default allocator will be returned.
 875  *
 876  * Returns: (transfer full): a #GstAllocator or NULL when the allocator with @name was not
 877  * registered. Use gst_allocator_unref() to release the allocator after usage.
 878  */
 879 GstAllocator *
 880 gst_allocator_find (const gchar * name)
 881 {
 882   GstAllocator *allocator;
 883
 884   g_rw_lock_reader_lock (&lock);
 885   if (name) {
 886     allocator = g_hash_table_lookup (allocators, (gconstpointer) name);
 887   } else {
 888     allocator = _default_allocator;
 889   }
 890   if (allocator)
 891     gst_allocator_ref (allocator);
 892   g_rw_lock_reader_unlock (&lock);
 893
 894   return allocator;
 895 }
 896
 897 /**
 898  * gst_allocator_set_default:
 899  * @allocator: (transfer full): a #GstAllocator
 900  *
 901  * Set the default allocator. This function takes ownership of @allocator.
 902  */
 903 void
 904 gst_allocator_set_default (GstAllocator * allocator)
 905 {
 906   GstAllocator *old;
 907   g_return_if_fail (allocator != NULL);
 908
 909   g_rw_lock_writer_lock (&lock);
 910   old = _default_allocator;
 911   _default_allocator = allocator;
 912   g_rw_lock_writer_unlock (&lock);
 913
 914   if (old)
 915     gst_allocator_unref (old);
 916 }
 917
 918 /**
 919  * gst_allocation_params_init:
 920  * @params: a #GstAllocationParams
 921  *
 922  * Initialize @params to its default values
 923  */
 924 void
 925 gst_allocation_params_init (GstAllocationParams * params)
 926 {
 927   g_return_if_fail (params != NULL);
 928
 929   memset (params, 0, sizeof (GstAllocationParams));
 930 }
 931
 932 /**
 933  * gst_allocation_params_copy:
 934  * @params: (transfer none): a #GstAllocationParams
 935  *
 936  * Create a copy of @params.
 937  *
 938  * Free-function: gst_allocation_params_free
 939  *
 940  * Returns: (transfer full): a new ##GstAllocationParams, free with
 941  * gst_allocation_params_free().
 942  */
 943 GstAllocationParams *
 944 gst_allocation_params_copy (const GstAllocationParams * params)
 945 {
 946   GstAllocationParams *result = NULL;
 947
 948   if (params) {
 949     result =
 950         (GstAllocationParams *) g_slice_copy (sizeof (GstAllocationParams),
 951         params);
 952   }
 953   return result;
 954 }
 955
 956 /**
 957  * gst_allocation_params_free:
 958  * @params: (in) (transfer full): a #GstAllocationParams
 959  *
 960  * Free @params
 961  */
 962 void
 963 gst_allocation_params_free (GstAllocationParams * params)
 964 {
 965   g_slice_free (GstAllocationParams, params);
 966 }
 967
 968 /**
 969  * gst_allocator_alloc:
 970  * @allocator: (transfer none) (allow-none): a #GstAllocator to use
 971  * @size: size of the visible memory area
 972  * @params: (transfer none) (allow-none): optional parameters
 973  *
 974  * Use @allocator to allocate a new memory block with memory that is at least
 975  * @size big.
 976  *
 977  * The optional @params can specify the prefix and padding for the memory. If
 978  * NULL is passed, no flags, no extra prefix/padding and a default alignment is
 979  * used.
 980  *
 981  * The prefix/padding will be filled with 0 if flags contains
 982  * #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
 983  *
 984  * When @allocator is NULL, the default allocator will be used.
 985  *
 986  * The alignment in @params is given as a bitmask so that @align + 1 equals
 987  * the amount of bytes to align to. For example, to align to 8 bytes,
 988  * use an alignment of 7.
 989  *
 990  * Returns: (transfer full): a new #GstMemory.
 991  */
 992 GstMemory *
 993 gst_allocator_alloc (GstAllocator * allocator, gsize size,
 994     GstAllocationParams * params)
 995 {
 996   GstMemory *mem;
 997   static GstAllocationParams defparams = { 0, 0, 0, 0, };
 998
 999   if (params) {
1000     g_return_val_if_fail (((params->align + 1) & params->align) == 0, NULL);
1001   } else {
1002     params = &defparams;
1003   }
1004
1005   if (allocator == NULL)
1006     allocator = _default_allocator;
1007
1008   mem = allocator->info.alloc (allocator, size, params, allocator->user_data);
1009
1010   return mem;
1011 }