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