gst/gstbufferpool.c

   1 /* GStreamer
   2  * Copyright (C) 2010 Wim Taymans <wim.taymans@gmail.com>
   3  *
   4  * gstbufferpool.c: GstBufferPool baseclass
   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:gstbufferpool
  24  * @short_description: Pool for buffers
  25  * @see_also: #GstBuffer
  26  *
  27  */
  28
  29 #include "gst_private.h"
  30 #include "glib-compat-private.h"
  31
  32 #include <errno.h>
  33 #ifdef HAVE_UNISTD_H
  34 #  include <unistd.h>
  35 #endif
  36 #include <sys/types.h>
  37
  38 #include "gstinfo.h"
  39 #include "gstquark.h"
  40
  41 #include "gstbufferpool.h"
  42
  43 GST_DEBUG_CATEGORY_STATIC (gst_buffer_pool_debug);
  44 #define GST_CAT_DEFAULT gst_buffer_pool_debug
  45
  46 #define GST_BUFFER_POOL_GET_PRIVATE(obj)  \
  47    (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_BUFFER_POOL, GstBufferPoolPrivate))
  48
  49 #define GST_BUFFER_POOL_LOCK(pool)   (g_static_rec_mutex_lock(&pool->priv->rec_lock))
  50 #define GST_BUFFER_POOL_UNLOCK(pool) (g_static_rec_mutex_unlock(&pool->priv->rec_lock))
  51
  52 struct _GstBufferPoolPrivate
  53 {
  54   GStaticRecMutex rec_lock;
  55   guint size;
  56   guint min_buffers;
  57   guint max_buffers;
  58   guint prefix;
  59   guint align;
  60 };
  61
  62 enum
  63 {
  64   /* add more above */
  65   LAST_SIGNAL
  66 };
  67
  68 static void gst_buffer_pool_finalize (GObject * object);
  69
  70 G_DEFINE_TYPE (GstBufferPool, gst_buffer_pool, GST_TYPE_OBJECT);
  71
  72 static gboolean default_start (GstBufferPool * pool);
  73 static gboolean default_stop (GstBufferPool * pool);
  74 static gboolean default_set_config (GstBufferPool * pool,
  75     GstStructure * config);
  76 static GstFlowReturn default_alloc_buffer (GstBufferPool * pool,
  77     GstBuffer ** buffer, GstBufferPoolParams * params);
  78 static GstFlowReturn default_acquire_buffer (GstBufferPool * pool,
  79     GstBuffer ** buffer, GstBufferPoolParams * params);
  80 static void default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
  81     GstBufferPoolParams * params);
  82 static void default_free_buffer (GstBufferPool * pool, GstBuffer * buffer);
  83 static void default_release_buffer (GstBufferPool * pool, GstBuffer * buffer);
  84
  85 static void
  86 gst_buffer_pool_class_init (GstBufferPoolClass * klass)
  87 {
  88   GObjectClass *gobject_class = (GObjectClass *) klass;
  89
  90   g_type_class_add_private (klass, sizeof (GstBufferPoolPrivate));
  91
  92   gobject_class->finalize = gst_buffer_pool_finalize;
  93
  94   klass->start = default_start;
  95   klass->stop = default_stop;
  96   klass->set_config = default_set_config;
  97   klass->acquire_buffer = default_acquire_buffer;
  98   klass->reset_buffer = default_reset_buffer;
  99   klass->alloc_buffer = default_alloc_buffer;
 100   klass->release_buffer = default_release_buffer;
 101   klass->free_buffer = default_free_buffer;
 102
 103   GST_DEBUG_CATEGORY_INIT (gst_buffer_pool_debug, "bufferpool", 0,
 104       "bufferpool debug");
 105 }
 106
 107 static void
 108 gst_buffer_pool_init (GstBufferPool * pool)
 109 {
 110   pool->priv = GST_BUFFER_POOL_GET_PRIVATE (pool);
 111
 112   g_static_rec_mutex_init (&pool->priv->rec_lock);
 113
 114   pool->poll = gst_poll_new_timer ();
 115   pool->queue = gst_atomic_queue_new (10);
 116   pool->flushing = TRUE;
 117   pool->active = FALSE;
 118   pool->configured = FALSE;
 119   pool->started = FALSE;
 120   pool->config = gst_structure_new_id_empty (GST_QUARK (BUFFER_POOL_CONFIG));
 121   gst_buffer_pool_config_set (pool->config, NULL, 0, 0, 0, 0, 0);
 122   gst_poll_write_control (pool->poll);
 123
 124   GST_DEBUG_OBJECT (pool, "created");
 125 }
 126
 127 static void
 128 gst_buffer_pool_finalize (GObject * object)
 129 {
 130   GstBufferPool *pool;
 131
 132   pool = GST_BUFFER_POOL_CAST (object);
 133
 134   GST_DEBUG_OBJECT (pool, "finalize");
 135
 136   gst_buffer_pool_set_active (pool, FALSE);
 137   gst_atomic_queue_unref (pool->queue);
 138   gst_poll_free (pool->poll);
 139   gst_structure_free (pool->config);
 140   g_static_rec_mutex_free (&pool->priv->rec_lock);
 141
 142   G_OBJECT_CLASS (gst_buffer_pool_parent_class)->finalize (object);
 143 }
 144
 145 /**
 146  * gst_buffer_pool_new:
 147  *
 148  * Creates a new #GstBufferPool instance.
 149  *
 150  * Returns: (transfer full): a new #GstBufferPool instance
 151  */
 152 GstBufferPool *
 153 gst_buffer_pool_new (void)
 154 {
 155   GstBufferPool *result;
 156
 157   result = g_object_newv (GST_TYPE_BUFFER_POOL, 0, NULL);
 158   GST_DEBUG_OBJECT (result, "created new buffer pool");
 159
 160   return result;
 161 }
 162
 163 static GstFlowReturn
 164 default_alloc_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 165     GstBufferPoolParams * params)
 166 {
 167   GstBufferPoolPrivate *priv = pool->priv;
 168   GstMemory *mem;
 169
 170   *buffer = gst_buffer_new ();
 171
 172   mem = gst_allocator_alloc (NULL, priv->size + priv->prefix, priv->align);
 173   gst_memory_resize (mem, priv->prefix, priv->size);
 174   gst_buffer_take_memory (*buffer, -1, mem);
 175
 176   return GST_FLOW_OK;
 177 }
 178
 179 static gboolean
 180 mark_meta_pooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
 181 {
 182   GST_META_FLAG_SET (*meta, GST_META_FLAG_POOLED);
 183
 184   return TRUE;
 185 }
 186
 187 /* the default implementation for preallocating the buffers
 188  * in the pool */
 189 static gboolean
 190 default_start (GstBufferPool * pool)
 191 {
 192   guint i;
 193   GstBufferPoolPrivate *priv = pool->priv;
 194   GstBufferPoolClass *pclass;
 195
 196   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 197
 198   /* no alloc function, error */
 199   if (G_UNLIKELY (pclass->alloc_buffer == NULL))
 200     goto no_alloc;
 201
 202   /* we need to prealloc buffers */
 203   for (i = 0; i < priv->min_buffers; i++) {
 204     GstBuffer *buffer;
 205
 206     if (pclass->alloc_buffer (pool, &buffer, NULL) != GST_FLOW_OK)
 207       goto alloc_failed;
 208
 209     gst_buffer_foreach_meta (buffer, mark_meta_pooled, pool);
 210     GST_LOG_OBJECT (pool, "prealloced buffer %d: %p", i, buffer);
 211     /* release to the queue, we call the vmethod directly, we don't need to do
 212      * the other refcount handling right now. */
 213     if (G_LIKELY (pclass->release_buffer))
 214       pclass->release_buffer (pool, buffer);
 215   }
 216   return TRUE;
 217
 218   /* ERRORS */
 219 no_alloc:
 220   {
 221     GST_WARNING_OBJECT (pool, "no alloc function");
 222     return FALSE;
 223   }
 224 alloc_failed:
 225   {
 226     GST_WARNING_OBJECT (pool, "alloc function failed");
 227     return FALSE;
 228   }
 229 }
 230
 231 /* must be called with the lock */
 232 static gboolean
 233 do_start (GstBufferPool * pool)
 234 {
 235   if (!pool->started) {
 236     GstBufferPoolClass *pclass;
 237
 238     pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 239
 240     GST_LOG_OBJECT (pool, "starting");
 241     /* start the pool, subclasses should allocate buffers and put them
 242      * in the queue */
 243     if (G_LIKELY (pclass->start)) {
 244       if (!pclass->start (pool))
 245         return FALSE;
 246     }
 247     pool->started = TRUE;
 248   }
 249   return TRUE;
 250 }
 251
 252
 253 static void
 254 default_free_buffer (GstBufferPool * pool, GstBuffer * buffer)
 255 {
 256   gst_buffer_unref (buffer);
 257 }
 258
 259 /* must be called with the lock */
 260 static gboolean
 261 default_stop (GstBufferPool * pool)
 262 {
 263   GstBuffer *buffer;
 264   GstBufferPoolClass *pclass;
 265
 266   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 267
 268   /* clear the pool */
 269   while ((buffer = gst_atomic_queue_pop (pool->queue))) {
 270     GST_LOG_OBJECT (pool, "freeing %p", buffer);
 271     gst_poll_read_control (pool->poll);
 272
 273     if (G_LIKELY (pclass->free_buffer))
 274       pclass->free_buffer (pool, buffer);
 275   }
 276   return TRUE;
 277 }
 278
 279 /* must be called with the lock */
 280 static gboolean
 281 do_stop (GstBufferPool * pool)
 282 {
 283   if (pool->started) {
 284     GstBufferPoolClass *pclass;
 285
 286     pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 287
 288     GST_LOG_OBJECT (pool, "stopping");
 289     if (G_LIKELY (pclass->stop)) {
 290       if (!pclass->stop (pool))
 291         return FALSE;
 292     }
 293     pool->started = FALSE;
 294   }
 295   return TRUE;
 296 }
 297
 298 /**
 299  * gst_buffer_pool_set_active:
 300  * @pool: a #GstBufferPool
 301  * @active: the new active state
 302  *
 303  * Control the active state of @pool. When the pool is active, new calls to
 304  * gst_buffer_pool_acquire_buffer() will return with GST_FLOW_WRONG_STATE.
 305  *
 306  * Activating the bufferpool will preallocate all resources in the pool based on
 307  * the configuration of the pool.
 308  *
 309  * Deactivating will free the resources again when there are no outstanding
 310  * buffers. When there are outstanding buffers, they will be freed as soon as
 311  * they are all returned to the pool.
 312  *
 313  * Returns: %FALSE when the pool was not configured or when preallocation of the
 314  * buffers failed.
 315  */
 316 gboolean
 317 gst_buffer_pool_set_active (GstBufferPool * pool, gboolean active)
 318 {
 319   gboolean res = TRUE;
 320
 321   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 322
 323   GST_LOG_OBJECT (pool, "active %d", active);
 324
 325   GST_BUFFER_POOL_LOCK (pool);
 326   /* just return if we are already in the right state */
 327   if (pool->active == active)
 328     goto was_ok;
 329
 330   /* we need to be configured */
 331   if (!pool->configured)
 332     goto not_configured;
 333
 334   if (active) {
 335     if (!do_start (pool))
 336       goto start_failed;
 337
 338     /* unset the flushing state now */
 339     gst_poll_read_control (pool->poll);
 340     g_atomic_int_set (&pool->flushing, FALSE);
 341   } else {
 342     gint outstanding;
 343
 344     /* set to flushing first */
 345     g_atomic_int_set (&pool->flushing, TRUE);
 346     gst_poll_write_control (pool->poll);
 347
 348     /* when all buffers are in the pool, free them. Else they will be
 349      * freed when they are released */
 350     outstanding = g_atomic_int_get (&pool->outstanding);
 351     GST_LOG_OBJECT (pool, "outstanding buffers %d", outstanding);
 352     if (outstanding == 0) {
 353       if (!do_stop (pool))
 354         goto stop_failed;
 355     }
 356   }
 357   pool->active = active;
 358   GST_BUFFER_POOL_UNLOCK (pool);
 359
 360   return res;
 361
 362 was_ok:
 363   {
 364     GST_DEBUG_OBJECT (pool, "pool was in the right state");
 365     GST_BUFFER_POOL_UNLOCK (pool);
 366     return TRUE;
 367   }
 368 not_configured:
 369   {
 370     GST_ERROR_OBJECT (pool, "pool was not configured");
 371     GST_BUFFER_POOL_UNLOCK (pool);
 372     return FALSE;
 373   }
 374 start_failed:
 375   {
 376     GST_ERROR_OBJECT (pool, "start failed");
 377     GST_BUFFER_POOL_UNLOCK (pool);
 378     return FALSE;
 379   }
 380 stop_failed:
 381   {
 382     GST_WARNING_OBJECT (pool, "stop failed");
 383     GST_BUFFER_POOL_UNLOCK (pool);
 384     return FALSE;
 385   }
 386 }
 387
 388 /**
 389  * gst_buffer_pool_is_active:
 390  * @pool: a #GstBufferPool
 391  *
 392  * Check if @pool is active. A pool can be activated with the
 393  * gst_buffer_pool_set_active() call.
 394  *
 395  * Returns: %TRUE when the pool is active.
 396  */
 397 gboolean
 398 gst_buffer_pool_is_active (GstBufferPool * pool)
 399 {
 400   gboolean res;
 401
 402   GST_BUFFER_POOL_LOCK (pool);
 403   res = pool->active;
 404   GST_BUFFER_POOL_UNLOCK (pool);
 405
 406   return res;
 407 }
 408
 409 static gboolean
 410 default_set_config (GstBufferPool * pool, GstStructure * config)
 411 {
 412   GstBufferPoolPrivate *priv = pool->priv;
 413   const GstCaps *caps;
 414   guint size, min_buffers, max_buffers;
 415   guint prefix, align;
 416
 417   /* parse the config and keep around */
 418   if (!gst_buffer_pool_config_get (config, &caps, &size, &min_buffers,
 419           &max_buffers, &prefix, &align))
 420     goto wrong_config;
 421
 422   GST_DEBUG_OBJECT (pool, "config %" GST_PTR_FORMAT, config);
 423
 424   priv->size = size;
 425   priv->min_buffers = min_buffers;
 426   priv->max_buffers = max_buffers;
 427   priv->prefix = prefix;
 428   priv->align = align;
 429
 430   return TRUE;
 431
 432 wrong_config:
 433   {
 434     GST_WARNING_OBJECT (pool, "invalid config %" GST_PTR_FORMAT, config);
 435     return FALSE;
 436   }
 437 }
 438
 439 /**
 440  * gst_buffer_pool_set_config:
 441  * @pool: a #GstBufferPool
 442  * @config: (transfer full): a #GstStructure
 443  *
 444  * Set the configuration of the pool. The pool must be inactive and all buffers
 445  * allocated form this pool must be returned or else this function will do
 446  * nothing and return FALSE.
 447  *
 448  * @config is a #GstStructure that contains the configuration parameters for
 449  * the pool. A default and mandatory set of parameters can be configured with
 450  * gst_buffer_pool_config_set(). This function takes ownership of @config.
 451  *
 452  * Returns: TRUE when the configuration could be set.
 453  */
 454 gboolean
 455 gst_buffer_pool_set_config (GstBufferPool * pool, GstStructure * config)
 456 {
 457   gboolean result;
 458   GstBufferPoolClass *pclass;
 459
 460   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 461   g_return_val_if_fail (config != NULL, FALSE);
 462
 463   GST_BUFFER_POOL_LOCK (pool);
 464   /* can't change the settings when active */
 465   if (pool->active)
 466     goto was_active;
 467
 468   /* we can't change when outstanding buffers */
 469   if (g_atomic_int_get (&pool->outstanding) != 0)
 470     goto have_outstanding;
 471
 472   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 473
 474   /* set the new config */
 475   if (G_LIKELY (pclass->set_config))
 476     result = pclass->set_config (pool, config);
 477   else
 478     result = FALSE;
 479
 480   if (result) {
 481     if (pool->config)
 482       gst_structure_free (pool->config);
 483     pool->config = config;
 484
 485     /* now we are configured */
 486     pool->configured = TRUE;
 487   }
 488   GST_BUFFER_POOL_UNLOCK (pool);
 489
 490   return result;
 491
 492   /* ERRORS */
 493 was_active:
 494   {
 495     GST_WARNING_OBJECT (pool, "can't change config, we are active");
 496     GST_BUFFER_POOL_UNLOCK (pool);
 497     return FALSE;
 498   }
 499 have_outstanding:
 500   {
 501     GST_WARNING_OBJECT (pool, "can't change config, have outstanding buffers");
 502     GST_BUFFER_POOL_UNLOCK (pool);
 503     return FALSE;
 504   }
 505 }
 506
 507 /**
 508  * gst_buffer_pool_get_config:
 509  * @pool: a #GstBufferPool
 510  *
 511  * Get a copy of the current configuration of the pool. This configuration
 512  * can either be modified and used for the gst_buffer_pool_set_config() call
 513  * or it must be freed after usage.
 514  *
 515  * Returns: (transfer full): a copy of the current configuration of @pool. use
 516  * gst_structure_free() after usage or gst_buffer_pool_set_config().
 517  */
 518 GstStructure *
 519 gst_buffer_pool_get_config (GstBufferPool * pool)
 520 {
 521   GstStructure *result;
 522
 523   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
 524
 525   GST_BUFFER_POOL_UNLOCK (pool);
 526   result = gst_structure_copy (pool->config);
 527   GST_BUFFER_POOL_UNLOCK (pool);
 528
 529   return result;
 530 }
 531
 532 static const gchar *empty_option[] = { NULL };
 533
 534 /**
 535  * gst_buffer_pool_get_options:
 536  * @pool: a #GstBufferPool
 537  *
 538  * Get a NULL terminated array of string with supported bufferpool options for
 539  * @pool. An option would typically be enabled with
 540  * gst_buffer_pool_config_add_option().
 541  *
 542  * Returns: (array zero-terminated=1) (transfer none): a NULL terminated array of strings.
 543  */
 544 const gchar **
 545 gst_buffer_pool_get_options (GstBufferPool * pool)
 546 {
 547   GstBufferPoolClass *pclass;
 548   const gchar **result;
 549
 550   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), NULL);
 551
 552   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 553
 554   if (G_LIKELY (pclass->get_options)) {
 555     if ((result = pclass->get_options (pool)) == NULL)
 556       goto invalid_result;
 557   } else
 558     result = empty_option;
 559
 560   return result;
 561
 562   /* ERROR */
 563 invalid_result:
 564   {
 565     g_warning ("bufferpool subclass returned NULL options");
 566     return empty_option;
 567   }
 568 }
 569
 570 /**
 571  * gst_buffer_pool_has_option:
 572  * @pool: a #GstBufferPool
 573  * @option: an option
 574  *
 575  * Check if the bufferpool supports @option.
 576  *
 577  * Returns: a NULL terminated array of strings.
 578  */
 579 gboolean
 580 gst_buffer_pool_has_option (GstBufferPool * pool, const gchar * option)
 581 {
 582   guint i;
 583   const gchar **options;
 584
 585   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), FALSE);
 586   g_return_val_if_fail (option != NULL, FALSE);
 587
 588   options = gst_buffer_pool_get_options (pool);
 589
 590   for (i = 0; options[i]; i++) {
 591     if (g_str_equal (options[i], option))
 592       return TRUE;
 593   }
 594   return FALSE;
 595 }
 596
 597 /**
 598  * gst_buffer_pool_config_set:
 599  * @config: a #GstBufferPool configuration
 600  * @caps: caps for the buffers
 601  * @size: the size of each buffer, not including prefix
 602  * @min_buffers: the minimum amount of buffers to allocate.
 603  * @max_buffers: the maximum amount of buffers to allocate or 0 for unlimited.
 604  * @prefix: prefix each buffer with this many bytes
 605  * @align: alignment of the buffer data.
 606  *
 607  * Configure @config with the given parameters.
 608  */
 609 void
 610 gst_buffer_pool_config_set (GstStructure * config, const GstCaps * caps,
 611     guint size, guint min_buffers, guint max_buffers, guint prefix, guint align)
 612 {
 613   g_return_if_fail (config != NULL);
 614
 615   gst_structure_id_set (config,
 616       GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
 617       GST_QUARK (SIZE), G_TYPE_UINT, size,
 618       GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
 619       GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers,
 620       GST_QUARK (PREFIX), G_TYPE_UINT, prefix,
 621       GST_QUARK (ALIGN), G_TYPE_UINT, align, NULL);
 622 }
 623
 624 /**
 625  * gst_buffer_pool_config_add_option:
 626  * @config: a #GstBufferPool configuration
 627  * @option: an option to add
 628  *
 629  * Enabled the option in @config. This will instruct the @bufferpool to enable
 630  * the specified option on the buffers that it allocates.
 631  *
 632  * The supported options by @pool can be retrieved with gst_buffer_pool_get_options().
 633  */
 634 void
 635 gst_buffer_pool_config_add_option (GstStructure * config, const gchar * option)
 636 {
 637   GValueArray *array;
 638   const GValue *value;
 639   GValue option_value = { 0 };
 640   gint i;
 641
 642   g_return_if_fail (config != NULL);
 643
 644   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 645   if (value) {
 646     array = (GValueArray *) g_value_get_boxed (value);
 647   } else {
 648     GValue new_array_val = { 0, };
 649
 650     array = g_value_array_new (0);
 651
 652     g_value_init (&new_array_val, G_TYPE_VALUE_ARRAY);
 653     g_value_take_boxed (&new_array_val, array);
 654
 655     gst_structure_id_take_value (config, GST_QUARK (OPTIONS), &new_array_val);
 656   }
 657   for (i = 0; i < array->n_values; i++) {
 658     value = g_value_array_get_nth (array, i);
 659     if (g_str_equal (option, g_value_get_string (value)))
 660       return;
 661   }
 662   g_value_init (&option_value, G_TYPE_STRING);
 663   g_value_set_string (&option_value, option);
 664   g_value_array_append (array, &option_value);
 665   g_value_unset (&option_value);
 666 }
 667
 668 /**
 669  * gst_buffer_pool_config_n_options:
 670  * @config: a #GstBufferPool configuration
 671  *
 672  * Retrieve the number of values currently stored in the
 673  * options array of the @config structure.
 674  *
 675  * Returns: the options array size as a #guint.
 676  */
 677 guint
 678 gst_buffer_pool_config_n_options (GstStructure * config)
 679 {
 680   GValueArray *array;
 681   const GValue *value;
 682   guint size = 0;
 683
 684   g_return_val_if_fail (config != NULL, 0);
 685
 686   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 687   if (value) {
 688     array = (GValueArray *) g_value_get_boxed (value);
 689     size = array->n_values;
 690   }
 691   return size;
 692 }
 693
 694 /**
 695  * gst_buffer_pool_config_get_option:
 696  * @config: a #GstBufferPool configuration
 697  * @index: position in the option array to read
 698  *
 699  * Parse an available @config and get the option
 700  * at @index of the options API array.
 701  *
 702  * Returns: a #gchar of the option at @index.
 703  */
 704 const gchar *
 705 gst_buffer_pool_config_get_option (GstStructure * config, guint index)
 706 {
 707   const GValue *value;
 708   const gchar *ret = NULL;
 709
 710   g_return_val_if_fail (config != NULL, 0);
 711
 712   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 713   if (value) {
 714     GValueArray *array;
 715     GValue *option_value;
 716
 717     array = (GValueArray *) g_value_get_boxed (value);
 718     option_value = g_value_array_get_nth (array, index);
 719
 720     if (option_value)
 721       ret = g_value_get_string (option_value);
 722   }
 723   return ret;
 724 }
 725
 726 /**
 727  * gst_buffer_pool_config_has_option:
 728  * @config: a #GstBufferPool configuration
 729  * @option: an option
 730  *
 731  * Check if @config contains @option
 732  *
 733  * Returns: TRUE if the options array contains @option.
 734  */
 735 gboolean
 736 gst_buffer_pool_config_has_option (GstStructure * config, const gchar * option)
 737 {
 738   const GValue *value;
 739
 740   g_return_val_if_fail (config != NULL, 0);
 741
 742   value = gst_structure_id_get_value (config, GST_QUARK (OPTIONS));
 743   if (value) {
 744     GValueArray *array;
 745     GValue *option_value;
 746     gint i;
 747
 748     array = (GValueArray *) g_value_get_boxed (value);
 749     for (i = 0; i < array->n_values; i++) {
 750       option_value = g_value_array_get_nth (array, i);
 751       if (g_str_equal (option, g_value_get_string (option_value)))
 752         return TRUE;
 753     }
 754   }
 755   return FALSE;
 756 }
 757
 758 /**
 759  * gst_buffer_pool_config_get:
 760  * @config: (transfer none): a #GstBufferPool configuration
 761  * @caps: (out): the caps of buffers
 762  * @size: (out): the size of each buffer, not including prefix
 763  * @min_buffers: (out): the minimum amount of buffers to allocate.
 764  * @max_buffers: (out): the maximum amount of buffers to allocate or 0 for unlimited.
 765  * @prefix: (out): prefix each buffer with this many bytes
 766  * @align: (out): alignment of the buffer data.
 767  *
 768  * Get the configuration values from @config.
 769  */
 770 gboolean
 771 gst_buffer_pool_config_get (GstStructure * config, const GstCaps ** caps,
 772     guint * size, guint * min_buffers, guint * max_buffers, guint * prefix,
 773     guint * align)
 774 {
 775   g_return_val_if_fail (config != NULL, FALSE);
 776
 777   return gst_structure_id_get (config,
 778       GST_QUARK (CAPS), GST_TYPE_CAPS, caps,
 779       GST_QUARK (SIZE), G_TYPE_UINT, size,
 780       GST_QUARK (MIN_BUFFERS), G_TYPE_UINT, min_buffers,
 781       GST_QUARK (MAX_BUFFERS), G_TYPE_UINT, max_buffers,
 782       GST_QUARK (PREFIX), G_TYPE_UINT, prefix,
 783       GST_QUARK (ALIGN), G_TYPE_UINT, align, NULL);
 784 }
 785
 786 static GstFlowReturn
 787 default_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 788     GstBufferPoolParams * params)
 789 {
 790   GstFlowReturn result;
 791   GstBufferPoolClass *pclass;
 792   GstBufferPoolPrivate *priv = pool->priv;
 793
 794   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 795
 796   while (TRUE) {
 797     if (G_UNLIKELY (g_atomic_int_get (&pool->flushing)))
 798       goto flushing;
 799
 800     /* try to get a buffer from the queue */
 801     *buffer = gst_atomic_queue_pop (pool->queue);
 802     if (G_LIKELY (*buffer)) {
 803       gst_poll_read_control (pool->poll);
 804       result = GST_FLOW_OK;
 805       GST_LOG_OBJECT (pool, "acquired buffer %p", *buffer);
 806       break;
 807     }
 808
 809     /* no buffer */
 810     if (priv->max_buffers == 0) {
 811       /* no max_buffers, we allocate some more */
 812       if (G_LIKELY (pclass->alloc_buffer)) {
 813         result = pclass->alloc_buffer (pool, buffer, params);
 814         if (result == GST_FLOW_OK && *buffer)
 815           gst_buffer_foreach_meta (*buffer, mark_meta_pooled, pool);
 816         else
 817           result = GST_FLOW_ERROR;
 818       } else
 819         result = GST_FLOW_NOT_SUPPORTED;
 820       GST_LOG_OBJECT (pool, "alloc buffer %p", *buffer);
 821       break;
 822     }
 823
 824     /* check if we need to wait */
 825     if (params && (params->flags & GST_BUFFER_POOL_FLAG_DONTWAIT)) {
 826       GST_LOG_OBJECT (pool, "no more buffers");
 827       result = GST_FLOW_EOS;
 828       break;
 829     }
 830
 831     /* now wait */
 832     GST_LOG_OBJECT (pool, "waiting for free buffers");
 833     gst_poll_wait (pool->poll, GST_CLOCK_TIME_NONE);
 834   }
 835
 836   return result;
 837
 838   /* ERRORS */
 839 flushing:
 840   {
 841     GST_DEBUG_OBJECT (pool, "we are flushing");
 842     return GST_FLOW_WRONG_STATE;
 843   }
 844 }
 845
 846 static inline void
 847 dec_outstanding (GstBufferPool * pool)
 848 {
 849   if (g_atomic_int_dec_and_test (&pool->outstanding)) {
 850     /* all buffers are returned to the pool, see if we need to free them */
 851     if (g_atomic_int_get (&pool->flushing)) {
 852       /* take the lock so that set_active is not run concurrently */
 853       GST_BUFFER_POOL_LOCK (pool);
 854       /* recheck the flushing state in the lock, the pool could have been
 855        * set to active again */
 856       if (g_atomic_int_get (&pool->flushing))
 857         do_stop (pool);
 858
 859       GST_BUFFER_POOL_UNLOCK (pool);
 860     }
 861   }
 862 }
 863
 864 static gboolean
 865 remove_meta_unpooled (GstBuffer * buffer, GstMeta ** meta, gpointer user_data)
 866 {
 867   if (!GST_META_FLAG_IS_SET (*meta, GST_META_FLAG_POOLED))
 868     *meta = NULL;
 869   return TRUE;
 870 }
 871
 872 static void
 873 default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
 874     GstBufferPoolParams * params)
 875 {
 876   GST_BUFFER_FLAGS (buffer) = 0;
 877
 878   GST_BUFFER_PTS (buffer) = GST_CLOCK_TIME_NONE;
 879   GST_BUFFER_DTS (buffer) = GST_CLOCK_TIME_NONE;
 880   GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
 881   GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
 882   GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
 883
 884   /* remove all metadata without the POOLED flag */
 885   gst_buffer_foreach_meta (buffer, remove_meta_unpooled, pool);
 886 }
 887
 888 /**
 889  * gst_buffer_pool_acquire_buffer:
 890  * @pool: a #GstBufferPool
 891  * @buffer: (out): a location for a #GstBuffer
 892  * @params: (transfer none) (allow-none) parameters.
 893  *
 894  * Acquire a buffer from @pool. @buffer should point to a memory location that
 895  * can hold a pointer to the new buffer.
 896  *
 897  * @params can be NULL or contain optional parameters to influence the allocation.
 898  *
 899  * Returns: a #GstFlowReturn such as GST_FLOW_WRONG_STATE when the pool is
 900  * inactive.
 901  */
 902 GstFlowReturn
 903 gst_buffer_pool_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
 904     GstBufferPoolParams * params)
 905 {
 906   GstBufferPoolClass *pclass;
 907   GstFlowReturn result;
 908
 909   g_return_val_if_fail (GST_IS_BUFFER_POOL (pool), GST_FLOW_ERROR);
 910   g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
 911
 912   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 913
 914   /* assume we'll have one more outstanding buffer we need to do that so
 915    * that concurrent set_active doesn't clear the buffers */
 916   g_atomic_int_inc (&pool->outstanding);
 917
 918   if (G_LIKELY (pclass->acquire_buffer))
 919     result = pclass->acquire_buffer (pool, buffer, params);
 920   else
 921     result = GST_FLOW_NOT_SUPPORTED;
 922
 923   if (G_LIKELY (result == GST_FLOW_OK)) {
 924     /* all buffers from the pool point to the pool and have the refcount of the
 925      * pool incremented */
 926     (*buffer)->pool = gst_object_ref (pool);
 927     /* now reset the buffer when needed */
 928     if (G_LIKELY (pclass->reset_buffer))
 929       pclass->reset_buffer (pool, *buffer, params);
 930   } else {
 931     dec_outstanding (pool);
 932   }
 933
 934   return result;
 935 }
 936
 937 static void
 938 default_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
 939 {
 940   /* keep it around in our queue */
 941   GST_LOG_OBJECT (pool, "released buffer %p", buffer);
 942   gst_atomic_queue_push (pool->queue, buffer);
 943   gst_poll_write_control (pool->poll);
 944 }
 945
 946 /**
 947  * gst_buffer_pool_release_buffer:
 948  * @pool: a #GstBufferPool
 949  * @buffer: (transfer none): a #GstBuffer
 950  *
 951  * Release @buffer to @pool. @buffer should have previously been allocated from
 952  * @pool with gst_buffer_pool_acquire_buffer().
 953  *
 954  * This function is usually called automatically when the last ref on @buffer
 955  * disappears.
 956  */
 957 void
 958 gst_buffer_pool_release_buffer (GstBufferPool * pool, GstBuffer * buffer)
 959 {
 960   GstBufferPoolClass *pclass;
 961
 962   g_return_if_fail (GST_IS_BUFFER_POOL (pool));
 963   g_return_if_fail (buffer != NULL);
 964
 965   /* check that the buffer is ours, all buffers returned to the pool have the
 966    * pool member set to NULL and the pool refcount decreased */
 967   if (!G_ATOMIC_POINTER_COMPARE_AND_EXCHANGE (&buffer->pool, pool, NULL))
 968     return;
 969
 970   pclass = GST_BUFFER_POOL_GET_CLASS (pool);
 971
 972   if (G_LIKELY (pclass->release_buffer))
 973     pclass->release_buffer (pool, buffer);
 974
 975   dec_outstanding (pool);
 976
 977   /* decrease the refcount that the buffer had to us */
 978   gst_object_unref (pool);
 979 }