gst-libs/gst/app/gstappsink.c

   1 /* GStreamer
   2  * Copyright (C) 2007 David Schleef <ds@schleef.org>
   3  *           (C) 2008 Wim Taymans <wim.taymans@gmail.com>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * SECTION:element-appsink
  23  * @see_also: #GstBaseSink, appsrc
  24  *
  25  * Appsink is a sink plugin that supports many different methods for making
  26  * the application get a handle on the GStreamer data in a pipeline.
  27  *
  28  * appsink can be used by linking to the gstappsink.h header file to access the
  29  * methods or by using the appsink action signals and properties.
  30  *
  31  * The normal way of retrieving buffers from appsink is by using the
  32  * gst_app_sink_pull_buffer() and gst_app_sink_pull_preroll() methods.
  33  * These methods block until a buffer becomes available in the sink or when the
  34  * sink is shut down or reaches EOS.
  35  *
  36  * Appsink will internally use a queue to collect buffers from the streaming
  37  * thread. If the application is not pulling buffers fast enough, this queue
  38  * will consume a lot of memory over time. The "max-buffers" property can be
  39  * used to limit the queue size. The "drop" property controls whether the
  40  * streaming thread blocks or if older buffers are dropped when the maximum
  41  * queue size is reached. Note that blocking the streaming thread can negatively
  42  * affect real-time performance and should be avoided.
  43  *
  44  * If a blocking behaviour is not desirable, setting the "emit-signals" property
  45  * to %TRUE will make appsink emit the "new-buffer" and "new-preroll" signals
  46  * when a buffer can be pulled without blocking.
  47  *
  48  * The "caps" property on appsink can be used to control the formats that
  49  * appsink can receive. This property can contain non-fixed caps, the format of
  50  * the pulled buffers can be obtained by getting the buffer caps.
  51  *
  52  * If one of the pull-preroll or pull-buffer methods return %NULL, the appsink
  53  * is stopped or in the EOS state. You can check for the EOS state with the
  54  * "eos" property or with the gst_app_sink_is_eos() method.
  55  *
  56  * The eos signal can also be used to be informed when the EOS state is reached
  57  * to avoid polling.
  58  *
  59  * Last reviewed on 2008-12-17 (0.10.10)
  60  */
  61
  62 #ifdef HAVE_CONFIG_H
  63 #include "config.h"
  64 #endif
  65
  66 #include <gst/gst.h>
  67 #include <gst/base/gstbasesink.h>
  68 #include <gst/gstbuffer.h>
  69
  70 #include <string.h>
  71
  72 #include "gstappsink.h"
  73
  74
  75 GST_DEBUG_CATEGORY (app_sink_debug);
  76 #define GST_CAT_DEFAULT app_sink_debug
  77
  78 static const GstElementDetails app_sink_details =
  79 GST_ELEMENT_DETAILS ("AppSink",
  80     "Generic/Sink",
  81     "Allow the application to get access to raw buffer",
  82     "David Schleef <ds@schleef.org>, Wim Taymans <wim.taymans@gmail.com>");
  83
  84 enum
  85 {
  86   /* signals */
  87   SIGNAL_EOS,
  88   SIGNAL_NEW_PREROLL,
  89   SIGNAL_NEW_BUFFER,
  90
  91   /* actions */
  92   SIGNAL_PULL_PREROLL,
  93   SIGNAL_PULL_BUFFER,
  94
  95   LAST_SIGNAL
  96 };
  97
  98 #define DEFAULT_PROP_EOS                TRUE
  99 #define DEFAULT_PROP_EMIT_SIGNALS       FALSE
 100 #define DEFAULT_PROP_MAX_BUFFERS        0
 101 #define DEFAULT_PROP_DROP               FALSE
 102
 103 enum
 104 {
 105   PROP_0,
 106   PROP_CAPS,
 107   PROP_EOS,
 108   PROP_EMIT_SIGNALS,
 109   PROP_MAX_BUFFERS,
 110   PROP_DROP,
 111   PROP_LAST
 112 };
 113
 114 static GstStaticPadTemplate gst_app_sink_template =
 115 GST_STATIC_PAD_TEMPLATE ("sink",
 116     GST_PAD_SINK,
 117     GST_PAD_ALWAYS,
 118     GST_STATIC_CAPS_ANY);
 119
 120 static void gst_app_sink_dispose (GObject * object);
 121 static void gst_app_sink_finalize (GObject * object);
 122
 123 static void gst_app_sink_set_property (GObject * object, guint prop_id,
 124     const GValue * value, GParamSpec * pspec);
 125 static void gst_app_sink_get_property (GObject * object, guint prop_id,
 126     GValue * value, GParamSpec * pspec);
 127
 128 static gboolean gst_app_sink_unlock_start (GstBaseSink * bsink);
 129 static gboolean gst_app_sink_unlock_stop (GstBaseSink * bsink);
 130 static gboolean gst_app_sink_start (GstBaseSink * psink);
 131 static gboolean gst_app_sink_stop (GstBaseSink * psink);
 132 static gboolean gst_app_sink_event (GstBaseSink * sink, GstEvent * event);
 133 static GstFlowReturn gst_app_sink_preroll (GstBaseSink * psink,
 134     GstBuffer * buffer);
 135 static GstFlowReturn gst_app_sink_render (GstBaseSink * psink,
 136     GstBuffer * buffer);
 137 static GstCaps *gst_app_sink_getcaps (GstBaseSink * psink);
 138
 139 static guint gst_app_sink_signals[LAST_SIGNAL] = { 0 };
 140
 141 GST_BOILERPLATE (GstAppSink, gst_app_sink, GstBaseSink, GST_TYPE_BASE_SINK);
 142
 143 void
 144 gst_app_marshal_OBJECT__VOID (GClosure * closure,
 145     GValue * return_value,
 146     guint n_param_values,
 147     const GValue * param_values,
 148     gpointer invocation_hint, gpointer marshal_data)
 149 {
 150   typedef GstBuffer *(*GMarshalFunc_OBJECT__VOID) (gpointer data1,
 151       gpointer data2);
 152   register GMarshalFunc_OBJECT__VOID callback;
 153   register GCClosure *cc = (GCClosure *) closure;
 154   register gpointer data1, data2;
 155   GstBuffer *v_return;
 156
 157   g_return_if_fail (return_value != NULL);
 158   g_return_if_fail (n_param_values == 1);
 159
 160   if (G_CCLOSURE_SWAP_DATA (closure)) {
 161     data1 = closure->data;
 162     data2 = g_value_peek_pointer (param_values + 0);
 163   } else {
 164     data1 = g_value_peek_pointer (param_values + 0);
 165     data2 = closure->data;
 166   }
 167   callback =
 168       (GMarshalFunc_OBJECT__VOID) (marshal_data ? marshal_data : cc->callback);
 169
 170   v_return = callback (data1, data2);
 171
 172   gst_value_take_buffer (return_value, v_return);
 173 }
 174
 175 static void
 176 gst_app_sink_base_init (gpointer g_class)
 177 {
 178   GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
 179
 180   GST_DEBUG_CATEGORY_INIT (app_sink_debug, "appsink", 0, "appsink element");
 181
 182   gst_element_class_set_details (element_class, &app_sink_details);
 183
 184   gst_element_class_add_pad_template (element_class,
 185       gst_static_pad_template_get (&gst_app_sink_template));
 186 }
 187
 188 static void
 189 gst_app_sink_class_init (GstAppSinkClass * klass)
 190 {
 191   GObjectClass *gobject_class = (GObjectClass *) klass;
 192   GstBaseSinkClass *basesink_class = (GstBaseSinkClass *) klass;
 193
 194   gobject_class->dispose = gst_app_sink_dispose;
 195   gobject_class->finalize = gst_app_sink_finalize;
 196
 197   gobject_class->set_property = gst_app_sink_set_property;
 198   gobject_class->get_property = gst_app_sink_get_property;
 199
 200   g_object_class_install_property (gobject_class, PROP_CAPS,
 201       g_param_spec_boxed ("caps", "Caps",
 202           "The allowed caps for the sink pad", GST_TYPE_CAPS,
 203           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 204
 205   g_object_class_install_property (gobject_class, PROP_EOS,
 206       g_param_spec_boolean ("eos", "EOS",
 207           "Check if the sink is EOS or not started", DEFAULT_PROP_EOS,
 208           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 209
 210   g_object_class_install_property (gobject_class, PROP_EMIT_SIGNALS,
 211       g_param_spec_boolean ("emit-signals", "Emit signals",
 212           "Emit new-preroll and new-buffer signals", DEFAULT_PROP_EMIT_SIGNALS,
 213           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 214
 215   g_object_class_install_property (gobject_class, PROP_MAX_BUFFERS,
 216       g_param_spec_uint ("max-buffers", "Max Buffers",
 217           "The maximum number of buffers to queue internally (0 = unlimited)",
 218           0, G_MAXUINT, DEFAULT_PROP_MAX_BUFFERS,
 219           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 220
 221   g_object_class_install_property (gobject_class, PROP_DROP,
 222       g_param_spec_boolean ("drop", "Drop",
 223           "Drop old buffers when the buffer queue is filled", DEFAULT_PROP_DROP,
 224           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 225
 226   /**
 227    * GstAppSink::eos:
 228    * @appsink: the appsink element that emited the signal
 229    *
 230    * Signal that the end-of-stream has been reached. This signal is emited from
 231    * the steaming thread.
 232    */
 233   gst_app_sink_signals[SIGNAL_EOS] =
 234       g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 235       G_STRUCT_OFFSET (GstAppSinkClass, eos),
 236       NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
 237   /**
 238    * GstAppSink::new-preroll:
 239    * @appsink: the appsink element that emited the signal
 240    *
 241    * Signal that a new preroll buffer is available.
 242    *
 243    * This signal is emited from the steaming thread and only when the
 244    * "emit-signals" property is %TRUE.
 245    *
 246    * The new preroll buffer can be retrieved with the "pull-preroll" action
 247    * signal or gst_app_sink_pull_preroll() either from this signal callback
 248    * or from any other thread.
 249    *
 250    * Note that this signal is only emited when the "emit-signals" property is
 251    * set to %TRUE, which it is not by default for performance reasons.
 252    */
 253   gst_app_sink_signals[SIGNAL_NEW_PREROLL] =
 254       g_signal_new ("new-preroll", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 255       G_STRUCT_OFFSET (GstAppSinkClass, new_preroll),
 256       NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
 257   /**
 258    * GstAppSink::new-buffer:
 259    * @appsink: the appsink element that emited the signal
 260    *
 261    * Signal that a new buffer is available.
 262    *
 263    * This signal is emited from the steaming thread and only when the
 264    * "emit-signals" property is %TRUE.
 265    *
 266    * The new buffer can be retrieved with the "pull-buffer" action
 267    * signal or gst_app_sink_pull_buffer() either from this signal callback
 268    * or from any other thread.
 269    *
 270    * Note that this signal is only emited when the "emit-signals" property is
 271    * set to %TRUE, which it is not by default for performance reasons.
 272    */
 273   gst_app_sink_signals[SIGNAL_NEW_BUFFER] =
 274       g_signal_new ("new-buffer", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 275       G_STRUCT_OFFSET (GstAppSinkClass, new_buffer),
 276       NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
 277
 278   /**
 279    * GstAppSink::pull-preroll:
 280    * @appsink: the appsink element to emit this signal on
 281    *
 282    * Get the last preroll buffer in @appsink. This was the buffer that caused the
 283    * appsink to preroll in the PAUSED state. This buffer can be pulled many times
 284    * and remains available to the application even after EOS.
 285    *
 286    * This function is typically used when dealing with a pipeline in the PAUSED
 287    * state. Calling this function after doing a seek will give the buffer right
 288    * after the seek position.
 289    *
 290    * Note that the preroll buffer will also be returned as the first buffer
 291    * when calling gst_app_sink_pull_buffer() or the "pull-buffer" action signal.
 292    *
 293    * If an EOS event was received before any buffers, this function returns
 294    * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 295    *
 296    * This function blocks until a preroll buffer or EOS is received or the appsink
 297    * element is set to the READY/NULL state.
 298    *
 299    * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
 300    */
 301   gst_app_sink_signals[SIGNAL_PULL_PREROLL] =
 302       g_signal_new ("pull-preroll", G_TYPE_FROM_CLASS (klass),
 303       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
 304           pull_preroll), NULL, NULL, gst_app_marshal_OBJECT__VOID,
 305       GST_TYPE_BUFFER, 0, G_TYPE_NONE);
 306   /**
 307    * GstAppSink::pull-buffer:
 308    * @appsink: the appsink element to emit this signal on
 309    *
 310    * This function blocks until a buffer or EOS becomes available or the appsink
 311    * element is set to the READY/NULL state.
 312    *
 313    * This function will only return buffers when the appsink is in the PLAYING
 314    * state. All rendered buffers will be put in a queue so that the application
 315    * can pull buffers at its own rate.
 316    *
 317    * Note that when the application does not pull buffers fast enough, the
 318    * queued buffers could consume a lot of memory, especially when dealing with
 319    * raw video frames. It's possible to control the behaviour of the queue with
 320    * the "drop" and "max-buffers" properties.
 321    *
 322    * If an EOS event was received before any buffers, this function returns
 323    * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 324    *
 325    * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
 326    */
 327   gst_app_sink_signals[SIGNAL_PULL_PREROLL] =
 328       g_signal_new ("pull-buffer", G_TYPE_FROM_CLASS (klass),
 329       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
 330           pull_buffer), NULL, NULL, gst_app_marshal_OBJECT__VOID,
 331       GST_TYPE_BUFFER, 0, G_TYPE_NONE);
 332
 333   basesink_class->unlock = gst_app_sink_unlock_start;
 334   basesink_class->unlock_stop = gst_app_sink_unlock_stop;
 335   basesink_class->start = gst_app_sink_start;
 336   basesink_class->stop = gst_app_sink_stop;
 337   basesink_class->event = gst_app_sink_event;
 338   basesink_class->preroll = gst_app_sink_preroll;
 339   basesink_class->render = gst_app_sink_render;
 340   basesink_class->get_caps = gst_app_sink_getcaps;
 341
 342   klass->pull_preroll = gst_app_sink_pull_preroll;
 343   klass->pull_buffer = gst_app_sink_pull_buffer;
 344 }
 345
 346 static void
 347 gst_app_sink_init (GstAppSink * appsink, GstAppSinkClass * klass)
 348 {
 349   appsink->mutex = g_mutex_new ();
 350   appsink->cond = g_cond_new ();
 351   appsink->queue = g_queue_new ();
 352
 353   appsink->emit_signals = DEFAULT_PROP_EMIT_SIGNALS;
 354   appsink->max_buffers = DEFAULT_PROP_MAX_BUFFERS;
 355   appsink->drop = DEFAULT_PROP_DROP;
 356 }
 357
 358 static void
 359 gst_app_sink_dispose (GObject * obj)
 360 {
 361   GstAppSink *appsink = GST_APP_SINK (obj);
 362   GstBuffer *buffer;
 363
 364   GST_OBJECT_LOCK (appsink);
 365   if (appsink->caps) {
 366     gst_caps_unref (appsink->caps);
 367     appsink->caps = NULL;
 368   }
 369   GST_OBJECT_UNLOCK (appsink);
 370
 371   g_mutex_lock (appsink->mutex);
 372   if (appsink->preroll) {
 373     gst_buffer_unref (appsink->preroll);
 374     appsink->preroll = NULL;
 375   }
 376   while ((buffer = g_queue_pop_head (appsink->queue)))
 377     gst_buffer_unref (buffer);
 378   g_mutex_unlock (appsink->mutex);
 379
 380   G_OBJECT_CLASS (parent_class)->dispose (obj);
 381 }
 382
 383 static void
 384 gst_app_sink_finalize (GObject * obj)
 385 {
 386   GstAppSink *appsink = GST_APP_SINK (obj);
 387
 388   g_mutex_free (appsink->mutex);
 389   g_cond_free (appsink->cond);
 390   g_queue_free (appsink->queue);
 391
 392   G_OBJECT_CLASS (parent_class)->finalize (obj);
 393 }
 394
 395 static void
 396 gst_app_sink_set_property (GObject * object, guint prop_id,
 397     const GValue * value, GParamSpec * pspec)
 398 {
 399   GstAppSink *appsink = GST_APP_SINK (object);
 400
 401   switch (prop_id) {
 402     case PROP_CAPS:
 403       gst_app_sink_set_caps (appsink, gst_value_get_caps (value));
 404       break;
 405     case PROP_EMIT_SIGNALS:
 406       gst_app_sink_set_emit_signals (appsink, g_value_get_boolean (value));
 407       break;
 408     case PROP_MAX_BUFFERS:
 409       gst_app_sink_set_max_buffers (appsink, g_value_get_uint (value));
 410       break;
 411     case PROP_DROP:
 412       gst_app_sink_set_drop (appsink, g_value_get_boolean (value));
 413       break;
 414     default:
 415       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 416       break;
 417   }
 418 }
 419
 420 static void
 421 gst_app_sink_get_property (GObject * object, guint prop_id, GValue * value,
 422     GParamSpec * pspec)
 423 {
 424   GstAppSink *appsink = GST_APP_SINK (object);
 425
 426   switch (prop_id) {
 427     case PROP_CAPS:
 428     {
 429       GstCaps *caps;
 430
 431       caps = gst_app_sink_get_caps (appsink);
 432       gst_value_set_caps (value, caps);
 433       if (caps)
 434         gst_caps_unref (caps);
 435       break;
 436     }
 437     case PROP_EOS:
 438       g_value_set_boolean (value, gst_app_sink_is_eos (appsink));
 439       break;
 440     case PROP_EMIT_SIGNALS:
 441       g_value_set_boolean (value, gst_app_sink_get_emit_signals (appsink));
 442       break;
 443     case PROP_MAX_BUFFERS:
 444       g_value_set_uint (value, gst_app_sink_get_max_buffers (appsink));
 445       break;
 446     case PROP_DROP:
 447       g_value_set_boolean (value, gst_app_sink_get_drop (appsink));
 448       break;
 449     default:
 450       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 451       break;
 452   }
 453 }
 454
 455 static gboolean
 456 gst_app_sink_unlock_start (GstBaseSink * bsink)
 457 {
 458   GstAppSink *appsink = GST_APP_SINK (bsink);
 459
 460   g_mutex_lock (appsink->mutex);
 461   GST_DEBUG_OBJECT (appsink, "unlock start");
 462   appsink->flushing = TRUE;
 463   g_cond_signal (appsink->cond);
 464   g_mutex_unlock (appsink->mutex);
 465
 466   return TRUE;
 467 }
 468
 469 static gboolean
 470 gst_app_sink_unlock_stop (GstBaseSink * bsink)
 471 {
 472   GstAppSink *appsink = GST_APP_SINK (bsink);
 473
 474   g_mutex_lock (appsink->mutex);
 475   GST_DEBUG_OBJECT (appsink, "unlock stop");
 476   appsink->flushing = FALSE;
 477   g_cond_signal (appsink->cond);
 478   g_mutex_unlock (appsink->mutex);
 479
 480   return TRUE;
 481 }
 482
 483 static void
 484 gst_app_sink_flush_unlocked (GstAppSink * appsink)
 485 {
 486   GstBuffer *buffer;
 487
 488   GST_DEBUG_OBJECT (appsink, "flush stop appsink");
 489   appsink->is_eos = FALSE;
 490   gst_buffer_replace (&appsink->preroll, NULL);
 491   while ((buffer = g_queue_pop_head (appsink->queue)))
 492     gst_buffer_unref (buffer);
 493   g_cond_signal (appsink->cond);
 494 }
 495
 496 static gboolean
 497 gst_app_sink_start (GstBaseSink * psink)
 498 {
 499   GstAppSink *appsink = GST_APP_SINK (psink);
 500
 501   g_mutex_lock (appsink->mutex);
 502   GST_DEBUG_OBJECT (appsink, "starting");
 503   appsink->started = TRUE;
 504   g_mutex_unlock (appsink->mutex);
 505
 506   return TRUE;
 507 }
 508
 509 static gboolean
 510 gst_app_sink_stop (GstBaseSink * psink)
 511 {
 512   GstAppSink *appsink = GST_APP_SINK (psink);
 513
 514   g_mutex_lock (appsink->mutex);
 515   GST_DEBUG_OBJECT (appsink, "stopping");
 516   appsink->flushing = TRUE;
 517   appsink->started = FALSE;
 518   gst_app_sink_flush_unlocked (appsink);
 519   g_mutex_unlock (appsink->mutex);
 520
 521   return TRUE;
 522 }
 523
 524 static gboolean
 525 gst_app_sink_event (GstBaseSink * sink, GstEvent * event)
 526 {
 527   GstAppSink *appsink = GST_APP_SINK (sink);
 528
 529   switch (event->type) {
 530     case GST_EVENT_EOS:
 531
 532       g_mutex_lock (appsink->mutex);
 533       GST_DEBUG_OBJECT (appsink, "receiving EOS");
 534       appsink->is_eos = TRUE;
 535       g_cond_signal (appsink->cond);
 536       g_mutex_unlock (appsink->mutex);
 537
 538       /* emit EOS now */
 539       g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_EOS], 0);
 540       break;
 541     case GST_EVENT_FLUSH_START:
 542       /* we don't have to do anything here, the base class will call unlock
 543        * which will make sure we exit the _render method */
 544       GST_DEBUG_OBJECT (appsink, "received FLUSH_START");
 545       break;
 546     case GST_EVENT_FLUSH_STOP:
 547       g_mutex_lock (appsink->mutex);
 548       GST_DEBUG_OBJECT (appsink, "received FLUSH_STOP");
 549       gst_app_sink_flush_unlocked (appsink);
 550       g_mutex_unlock (appsink->mutex);
 551       break;
 552     default:
 553       break;
 554   }
 555   return TRUE;
 556 }
 557
 558 static GstFlowReturn
 559 gst_app_sink_preroll (GstBaseSink * psink, GstBuffer * buffer)
 560 {
 561   GstAppSink *appsink = GST_APP_SINK (psink);
 562   gboolean emit;
 563
 564   g_mutex_lock (appsink->mutex);
 565   if (appsink->flushing)
 566     goto flushing;
 567
 568   GST_DEBUG_OBJECT (appsink, "setting preroll buffer %p", buffer);
 569   gst_buffer_replace (&appsink->preroll, buffer);
 570   g_cond_signal (appsink->cond);
 571   emit = appsink->emit_signals;
 572   g_mutex_unlock (appsink->mutex);
 573
 574   if (emit)
 575     g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_PREROLL], 0);
 576
 577   return GST_FLOW_OK;
 578
 579 flushing:
 580   {
 581     GST_DEBUG_OBJECT (appsink, "we are flushing");
 582     g_mutex_unlock (appsink->mutex);
 583     return GST_FLOW_WRONG_STATE;
 584   }
 585 }
 586
 587 static GstFlowReturn
 588 gst_app_sink_render (GstBaseSink * psink, GstBuffer * buffer)
 589 {
 590   GstAppSink *appsink = GST_APP_SINK (psink);
 591   gboolean emit;
 592
 593   g_mutex_lock (appsink->mutex);
 594   if (appsink->flushing)
 595     goto flushing;
 596
 597   GST_DEBUG_OBJECT (appsink, "pushing render buffer %p on queue (%d)",
 598       buffer, appsink->queue->length);
 599
 600   while (appsink->max_buffers > 0 &&
 601       appsink->queue->length >= appsink->max_buffers) {
 602     if (appsink->drop) {
 603       GstBuffer *buf;
 604
 605       /* we need to drop the oldest buffer and try again */
 606       buf = g_queue_pop_head (appsink->queue);
 607       GST_DEBUG_OBJECT (appsink, "dropping old buffer %p", buf);
 608       gst_buffer_unref (buf);
 609     } else {
 610       GST_DEBUG_OBJECT (appsink, "waiting for free space, length %d >= %d",
 611           appsink->queue->length, appsink->max_buffers);
 612       /* wait for a buffer to be removed or flush */
 613       g_cond_wait (appsink->cond, appsink->mutex);
 614       if (appsink->flushing)
 615         goto flushing;
 616     }
 617   }
 618   /* we need to ref the buffer when pushing it in the queue */
 619   g_queue_push_tail (appsink->queue, gst_buffer_ref (buffer));
 620   g_cond_signal (appsink->cond);
 621   emit = appsink->emit_signals;
 622   g_mutex_unlock (appsink->mutex);
 623
 624   if (emit)
 625     g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER], 0);
 626
 627   return GST_FLOW_OK;
 628
 629 flushing:
 630   {
 631     GST_DEBUG_OBJECT (appsink, "we are flushing");
 632     g_mutex_unlock (appsink->mutex);
 633     return GST_FLOW_WRONG_STATE;
 634   }
 635 }
 636
 637 static GstCaps *
 638 gst_app_sink_getcaps (GstBaseSink * psink)
 639 {
 640   GstCaps *caps;
 641
 642   GstAppSink *appsink = GST_APP_SINK (psink);
 643
 644   GST_OBJECT_LOCK (appsink);
 645   if ((caps = appsink->caps))
 646     gst_caps_ref (caps);
 647   GST_DEBUG_OBJECT (appsink, "got caps %" GST_PTR_FORMAT, caps);
 648   GST_OBJECT_UNLOCK (appsink);
 649
 650   return caps;
 651 }
 652
 653 /* external API */
 654
 655 /**
 656  * gst_app_sink_set_caps:
 657  * @appsink: a #GstAppSink
 658  * @caps: caps to set
 659  *
 660  * Set the capabilities on the appsink element.  This function takes
 661  * a copy of the caps structure. After calling this method, the sink will only
 662  * accept caps that match @caps. If @caps is non-fixed, you must check the caps
 663  * on the buffers to get the actual used caps.
 664  */
 665 void
 666 gst_app_sink_set_caps (GstAppSink * appsink, const GstCaps * caps)
 667 {
 668   GstCaps *old;
 669
 670   g_return_if_fail (appsink != NULL);
 671   g_return_if_fail (GST_IS_APP_SINK (appsink));
 672
 673   GST_OBJECT_LOCK (appsink);
 674   GST_DEBUG_OBJECT (appsink, "setting caps to %" GST_PTR_FORMAT, caps);
 675   if ((old = appsink->caps) != caps) {
 676     if (caps)
 677       appsink->caps = gst_caps_copy (caps);
 678     else
 679       appsink->caps = NULL;
 680     if (old)
 681       gst_caps_unref (old);
 682   }
 683   GST_OBJECT_UNLOCK (appsink);
 684 }
 685
 686 /**
 687  * gst_app_sink_get_caps:
 688  * @appsink: a #GstAppSink
 689  *
 690  * Get the configured caps on @appsink.
 691  *
 692  * Returns: the #GstCaps accepted by the sink. gst_caps_unref() after usage.
 693  */
 694 GstCaps *
 695 gst_app_sink_get_caps (GstAppSink * appsink)
 696 {
 697   GstCaps *caps;
 698
 699   g_return_val_if_fail (appsink != NULL, NULL);
 700   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
 701
 702   GST_OBJECT_LOCK (appsink);
 703   if ((caps = appsink->caps))
 704     gst_caps_ref (caps);
 705   GST_DEBUG_OBJECT (appsink, "getting caps of %" GST_PTR_FORMAT, caps);
 706   GST_OBJECT_UNLOCK (appsink);
 707
 708   return caps;
 709 }
 710
 711 /**
 712  * gst_app_sink_is_eos:
 713  * @appsink: a #GstAppSink
 714  *
 715  * Check if @appsink is EOS, which is when no more buffers can be pulled because
 716  * an EOS event was received.
 717  *
 718  * This function also returns %TRUE when the appsink is not in the PAUSED or
 719  * PLAYING state.
 720  *
 721  * Returns: %TRUE if no more buffers can be pulled and the appsink is EOS.
 722  */
 723 gboolean
 724 gst_app_sink_is_eos (GstAppSink * appsink)
 725 {
 726   gboolean ret;
 727
 728   g_return_val_if_fail (appsink != NULL, FALSE);
 729   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
 730
 731   g_mutex_lock (appsink->mutex);
 732   if (!appsink->started)
 733     goto not_started;
 734
 735   if (appsink->is_eos && g_queue_is_empty (appsink->queue)) {
 736     GST_DEBUG_OBJECT (appsink, "we are EOS and the queue is empty");
 737     ret = TRUE;
 738   } else {
 739     GST_DEBUG_OBJECT (appsink, "we are not yet EOS");
 740     ret = FALSE;
 741   }
 742   g_mutex_unlock (appsink->mutex);
 743
 744   return ret;
 745
 746 not_started:
 747   {
 748     GST_DEBUG_OBJECT (appsink, "we are stopped, return TRUE");
 749     g_mutex_unlock (appsink->mutex);
 750     return TRUE;
 751   }
 752 }
 753
 754 /**
 755  * gst_app_sink_set_emit_signals:
 756  * @appsink: a #GstAppSink
 757  * @emit: the new state
 758  *
 759  * Make appsink emit the "new-preroll" and "new-buffer" signals. This option is
 760  * by default disabled because signal emission is expensive and unneeded when
 761  * the application prefers to operate in pull mode.
 762  */
 763 void
 764 gst_app_sink_set_emit_signals (GstAppSink * appsink, gboolean emit)
 765 {
 766   g_return_if_fail (GST_IS_APP_SINK (appsink));
 767
 768   g_mutex_lock (appsink->mutex);
 769   appsink->emit_signals = emit;
 770   g_mutex_unlock (appsink->mutex);
 771 }
 772
 773 /**
 774  * gst_app_sink_get_emit_signals:
 775  * @appsink: a #GstAppSink
 776  *
 777  * Check if appsink will emit the "new-preroll" and "new-buffer" signals.
 778  *
 779  * Returns: %TRUE if @appsink is emiting the "new-preroll" and "new-buffer"
 780  * signals.
 781  */
 782 gboolean
 783 gst_app_sink_get_emit_signals (GstAppSink * appsink)
 784 {
 785   gboolean result;
 786
 787   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
 788
 789   g_mutex_lock (appsink->mutex);
 790   result = appsink->emit_signals;
 791   g_mutex_unlock (appsink->mutex);
 792
 793   return result;
 794 }
 795
 796 /**
 797  * gst_app_sink_set_max_buffers:
 798  * @appsink: a #GstAppSink
 799  * @max: the maximum number of buffers to queue
 800  *
 801  * Set the maximum amount of buffers that can be queued in @appsink. After this
 802  * amount of buffers are queued in appsink, any more buffers will block upstream
 803  * elements until a buffer is pulled from @appsink.
 804  */
 805 void
 806 gst_app_sink_set_max_buffers (GstAppSink * appsink, guint max)
 807 {
 808   g_return_if_fail (GST_IS_APP_SINK (appsink));
 809
 810   g_mutex_lock (appsink->mutex);
 811   if (max != appsink->max_buffers) {
 812     appsink->max_buffers = max;
 813     /* signal the change */
 814     g_cond_signal (appsink->cond);
 815   }
 816   g_mutex_unlock (appsink->mutex);
 817 }
 818
 819 /**
 820  * gst_app_sink_get_max_buffers:
 821  * @appsink: a #GstAppSink
 822  *
 823  * Get the maximum amount of buffers that can be queued in @appsink.
 824  *
 825  * Returns: The maximum amount of buffers that can be queued.
 826  */
 827 guint
 828 gst_app_sink_get_max_buffers (GstAppSink * appsink)
 829 {
 830   guint result;
 831
 832   g_return_val_if_fail (GST_IS_APP_SINK (appsink), 0);
 833
 834   g_mutex_lock (appsink->mutex);
 835   result = appsink->max_buffers;
 836   g_mutex_unlock (appsink->mutex);
 837
 838   return result;
 839 }
 840
 841 /**
 842  * gst_app_sink_set_drop:
 843  * @appsink: a #GstAppSink
 844  * @emit: the new state
 845  *
 846  * Instruct @appsink to drop old buffers when the maximum amount of queued
 847  * buffers is reached.
 848  */
 849 void
 850 gst_app_sink_set_drop (GstAppSink * appsink, gboolean drop)
 851 {
 852   g_return_if_fail (GST_IS_APP_SINK (appsink));
 853
 854   g_mutex_lock (appsink->mutex);
 855   if (appsink->drop != drop) {
 856     appsink->drop = drop;
 857     /* signal the change */
 858     g_cond_signal (appsink->cond);
 859   }
 860   g_mutex_unlock (appsink->mutex);
 861 }
 862
 863 /**
 864  * gst_app_sink_get_drop:
 865  * @appsink: a #GstAppSink
 866  *
 867  * Check if @appsink will drop old buffers when the maximum amount of queued
 868  * buffers is reached.
 869  *
 870  * Returns: %TRUE if @appsink is dropping old buffers when the queue is
 871  * filled.
 872  */
 873 gboolean
 874 gst_app_sink_get_drop (GstAppSink * appsink)
 875 {
 876   gboolean result;
 877
 878   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
 879
 880   g_mutex_lock (appsink->mutex);
 881   result = appsink->drop;
 882   g_mutex_unlock (appsink->mutex);
 883
 884   return result;
 885 }
 886
 887 /**
 888  * gst_app_sink_pull_preroll:
 889  * @appsink: a #GstAppSink
 890  *
 891  * Get the last preroll buffer in @appsink. This was the buffer that caused the
 892  * appsink to preroll in the PAUSED state. This buffer can be pulled many times
 893  * and remains available to the application even after EOS.
 894  *
 895  * This function is typically used when dealing with a pipeline in the PAUSED
 896  * state. Calling this function after doing a seek will give the buffer right
 897  * after the seek position.
 898  *
 899  * Note that the preroll buffer will also be returned as the first buffer
 900  * when calling gst_app_sink_pull_buffer().
 901  *
 902  * If an EOS event was received before any buffers, this function returns
 903  * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 904  *
 905  * This function blocks until a preroll buffer or EOS is received or the appsink
 906  * element is set to the READY/NULL state.
 907  *
 908  * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
 909  */
 910 GstBuffer *
 911 gst_app_sink_pull_preroll (GstAppSink * appsink)
 912 {
 913   GstBuffer *buf = NULL;
 914
 915   g_return_val_if_fail (appsink != NULL, NULL);
 916   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
 917
 918   g_mutex_lock (appsink->mutex);
 919
 920   while (TRUE) {
 921     GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
 922     if (!appsink->started)
 923       goto not_started;
 924
 925     if (appsink->preroll != NULL)
 926       break;
 927
 928     if (appsink->is_eos)
 929       goto eos;
 930
 931     /* nothing to return, wait */
 932     GST_DEBUG_OBJECT (appsink, "waiting for the preroll buffer");
 933     g_cond_wait (appsink->cond, appsink->mutex);
 934   }
 935   buf = gst_buffer_ref (appsink->preroll);
 936   GST_DEBUG_OBJECT (appsink, "we have the preroll buffer %p", buf);
 937   g_mutex_unlock (appsink->mutex);
 938
 939   return buf;
 940
 941   /* special conditions */
 942 eos:
 943   {
 944     GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
 945     g_mutex_unlock (appsink->mutex);
 946     return NULL;
 947   }
 948 not_started:
 949   {
 950     GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
 951     g_mutex_unlock (appsink->mutex);
 952     return NULL;
 953   }
 954 }
 955
 956 /**
 957  * gst_app_sink_pull_buffer:
 958  * @appsink: a #GstAppSink
 959  *
 960  * This function blocks until a buffer or EOS becomes available or the appsink
 961  * element is set to the READY/NULL state.
 962  *
 963  * This function will only return buffers when the appsink is in the PLAYING
 964  * state. All rendered buffers will be put in a queue so that the application
 965  * can pull buffers at its own rate. Note that when the application does not
 966  * pull buffers fast enough, the queued buffers could consume a lot of memory,
 967  * especially when dealing with raw video frames.
 968  *
 969  * If an EOS event was received before any buffers, this function returns
 970  * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 971  *
 972  * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
 973  */
 974 GstBuffer *
 975 gst_app_sink_pull_buffer (GstAppSink * appsink)
 976 {
 977   GstBuffer *buf = NULL;
 978
 979   g_return_val_if_fail (appsink != NULL, NULL);
 980   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
 981
 982   g_mutex_lock (appsink->mutex);
 983
 984   while (TRUE) {
 985     GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
 986     if (!appsink->started)
 987       goto not_started;
 988
 989     if (!g_queue_is_empty (appsink->queue))
 990       break;
 991
 992     if (appsink->is_eos)
 993       goto eos;
 994
 995     /* nothing to return, wait */
 996     GST_DEBUG_OBJECT (appsink, "waiting for a buffer");
 997     g_cond_wait (appsink->cond, appsink->mutex);
 998   }
 999   buf = g_queue_pop_head (appsink->queue);
1000   GST_DEBUG_OBJECT (appsink, "we have a buffer %p", buf);
1001   g_cond_signal (appsink->cond);
1002   g_mutex_unlock (appsink->mutex);
1003
1004   return buf;
1005
1006   /* special conditions */
1007 eos:
1008   {
1009     GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
1010     g_mutex_unlock (appsink->mutex);
1011     return NULL;
1012   }
1013 not_started:
1014   {
1015     GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
1016     g_mutex_unlock (appsink->mutex);
1017     return NULL;
1018   }
1019 }