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., 51 Franklin St, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20 /**
  21  * SECTION:gstappsink
  22  * @short_description: Easy way for applications to extract samples from a
  23  *     pipeline
  24  * @see_also: #GstSample, #GstBaseSink, appsrc
  25  *
  26  * Appsink is a sink plugin that supports many different methods for making
  27  * the application get a handle on the GStreamer data in a pipeline. Unlike
  28  * most GStreamer elements, Appsink provides external API functions.
  29  *
  30  * appsink can be used by linking to the gstappsink.h header file to access the
  31  * methods or by using the appsink action signals and properties.
  32  *
  33  * The normal way of retrieving samples from appsink is by using the
  34  * gst_app_sink_pull_sample() and gst_app_sink_pull_preroll() methods.
  35  * These methods block until a sample becomes available in the sink or when the
  36  * sink is shut down or reaches EOS. There are also timed variants of these
  37  * methods, gst_app_sink_try_pull_sample() and gst_app_sink_try_pull_preroll(),
  38  * which accept a timeout parameter to limit the amount of time to wait.
  39  *
  40  * Appsink will internally use a queue to collect buffers from the streaming
  41  * thread. If the application is not pulling samples fast enough, this queue
  42  * will consume a lot of memory over time. The "max-buffers" property can be
  43  * used to limit the queue size. The "drop" property controls whether the
  44  * streaming thread blocks or if older buffers are dropped when the maximum
  45  * queue size is reached. Note that blocking the streaming thread can negatively
  46  * affect real-time performance and should be avoided.
  47  *
  48  * If a blocking behaviour is not desirable, setting the "emit-signals" property
  49  * to %TRUE will make appsink emit the "new-sample" and "new-preroll" signals
  50  * when a sample can be pulled without blocking.
  51  *
  52  * The "caps" property on appsink can be used to control the formats that
  53  * appsink can receive. This property can contain non-fixed caps, the format of
  54  * the pulled samples can be obtained by getting the sample caps.
  55  *
  56  * If one of the pull-preroll or pull-sample methods return %NULL, the appsink
  57  * is stopped or in the EOS state. You can check for the EOS state with the
  58  * "eos" property or with the gst_app_sink_is_eos() method.
  59  *
  60  * The eos signal can also be used to be informed when the EOS state is reached
  61  * to avoid polling.
  62  */
  63
  64 #ifdef HAVE_CONFIG_H
  65 #include "config.h"
  66 #endif
  67
  68 #include <gst/gst.h>
  69 #include <gst/base/gstbasesink.h>
  70 #include <gst/gstbuffer.h>
  71
  72 #include <string.h>
  73
  74 #include "gstappsink.h"
  75
  76 struct _GstAppSinkPrivate
  77 {
  78   GstCaps *caps;
  79   gboolean emit_signals;
  80   guint num_buffers;
  81   guint max_buffers;
  82   gboolean drop;
  83   gboolean wait_on_eos;
  84
  85   GCond cond;
  86   GMutex mutex;
  87   GQueue *queue;
  88   GstBuffer *preroll;
  89   GstCaps *preroll_caps;
  90   GstCaps *last_caps;
  91   GstSegment preroll_segment;
  92   GstSegment last_segment;
  93   gboolean flushing;
  94   gboolean unlock;
  95   gboolean started;
  96   gboolean is_eos;
  97
  98   GstAppSinkCallbacks callbacks;
  99   gpointer user_data;
 100   GDestroyNotify notify;
 101 };
 102
 103 GST_DEBUG_CATEGORY_STATIC (app_sink_debug);
 104 #define GST_CAT_DEFAULT app_sink_debug
 105
 106 enum
 107 {
 108   /* signals */
 109   SIGNAL_EOS,
 110   SIGNAL_NEW_PREROLL,
 111   SIGNAL_NEW_SAMPLE,
 112
 113   /* actions */
 114   SIGNAL_PULL_PREROLL,
 115   SIGNAL_PULL_SAMPLE,
 116   SIGNAL_TRY_PULL_PREROLL,
 117   SIGNAL_TRY_PULL_SAMPLE,
 118
 119   LAST_SIGNAL
 120 };
 121
 122 #define DEFAULT_PROP_EOS                TRUE
 123 #define DEFAULT_PROP_EMIT_SIGNALS       FALSE
 124 #define DEFAULT_PROP_MAX_BUFFERS        0
 125 #define DEFAULT_PROP_DROP               FALSE
 126 #define DEFAULT_PROP_WAIT_ON_EOS        TRUE
 127
 128 enum
 129 {
 130   PROP_0,
 131   PROP_CAPS,
 132   PROP_EOS,
 133   PROP_EMIT_SIGNALS,
 134   PROP_MAX_BUFFERS,
 135   PROP_DROP,
 136   PROP_WAIT_ON_EOS,
 137   PROP_LAST
 138 };
 139
 140 static GstStaticPadTemplate gst_app_sink_template =
 141 GST_STATIC_PAD_TEMPLATE ("sink",
 142     GST_PAD_SINK,
 143     GST_PAD_ALWAYS,
 144     GST_STATIC_CAPS_ANY);
 145
 146 static void gst_app_sink_uri_handler_init (gpointer g_iface,
 147     gpointer iface_data);
 148
 149 static void gst_app_sink_dispose (GObject * object);
 150 static void gst_app_sink_finalize (GObject * object);
 151
 152 static void gst_app_sink_set_property (GObject * object, guint prop_id,
 153     const GValue * value, GParamSpec * pspec);
 154 static void gst_app_sink_get_property (GObject * object, guint prop_id,
 155     GValue * value, GParamSpec * pspec);
 156
 157 static gboolean gst_app_sink_unlock_start (GstBaseSink * bsink);
 158 static gboolean gst_app_sink_unlock_stop (GstBaseSink * bsink);
 159 static gboolean gst_app_sink_start (GstBaseSink * psink);
 160 static gboolean gst_app_sink_stop (GstBaseSink * psink);
 161 static gboolean gst_app_sink_event (GstBaseSink * sink, GstEvent * event);
 162 static gboolean gst_app_sink_query (GstBaseSink * bsink, GstQuery * query);
 163 static GstFlowReturn gst_app_sink_preroll (GstBaseSink * psink,
 164     GstBuffer * buffer);
 165 static GstFlowReturn gst_app_sink_render (GstBaseSink * psink,
 166     GstBuffer * buffer);
 167 static gboolean gst_app_sink_setcaps (GstBaseSink * sink, GstCaps * caps);
 168 static GstCaps *gst_app_sink_getcaps (GstBaseSink * psink, GstCaps * filter);
 169
 170 static guint gst_app_sink_signals[LAST_SIGNAL] = { 0 };
 171
 172 #define gst_app_sink_parent_class parent_class
 173 G_DEFINE_TYPE_WITH_CODE (GstAppSink, gst_app_sink, GST_TYPE_BASE_SINK,
 174     G_IMPLEMENT_INTERFACE (GST_TYPE_URI_HANDLER,
 175         gst_app_sink_uri_handler_init));
 176
 177 static void
 178 gst_app_sink_class_init (GstAppSinkClass * klass)
 179 {
 180   GObjectClass *gobject_class = (GObjectClass *) klass;
 181   GstElementClass *element_class = (GstElementClass *) klass;
 182   GstBaseSinkClass *basesink_class = (GstBaseSinkClass *) klass;
 183
 184   GST_DEBUG_CATEGORY_INIT (app_sink_debug, "appsink", 0, "appsink element");
 185
 186   gobject_class->dispose = gst_app_sink_dispose;
 187   gobject_class->finalize = gst_app_sink_finalize;
 188
 189   gobject_class->set_property = gst_app_sink_set_property;
 190   gobject_class->get_property = gst_app_sink_get_property;
 191
 192   g_object_class_install_property (gobject_class, PROP_CAPS,
 193       g_param_spec_boxed ("caps", "Caps",
 194           "The allowed caps for the sink pad", GST_TYPE_CAPS,
 195           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 196
 197   g_object_class_install_property (gobject_class, PROP_EOS,
 198       g_param_spec_boolean ("eos", "EOS",
 199           "Check if the sink is EOS or not started", DEFAULT_PROP_EOS,
 200           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 201
 202   g_object_class_install_property (gobject_class, PROP_EMIT_SIGNALS,
 203       g_param_spec_boolean ("emit-signals", "Emit signals",
 204           "Emit new-preroll and new-sample signals",
 205           DEFAULT_PROP_EMIT_SIGNALS,
 206           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 207
 208   g_object_class_install_property (gobject_class, PROP_MAX_BUFFERS,
 209       g_param_spec_uint ("max-buffers", "Max Buffers",
 210           "The maximum number of buffers to queue internally (0 = unlimited)",
 211           0, G_MAXUINT, DEFAULT_PROP_MAX_BUFFERS,
 212           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 213
 214   g_object_class_install_property (gobject_class, PROP_DROP,
 215       g_param_spec_boolean ("drop", "Drop",
 216           "Drop old buffers when the buffer queue is filled", DEFAULT_PROP_DROP,
 217           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 218
 219   /**
 220    * GstAppSink::wait-on-eos:
 221    *
 222    * Wait for all buffers to be processed after receiving an EOS.
 223    *
 224    * In cases where it is uncertain if an @appsink will have a consumer for its buffers
 225    * when it receives an EOS, set to %FALSE to ensure that the @appsink will not hang.
 226    *
 227    * Since: 1.8
 228    */
 229   g_object_class_install_property (gobject_class, PROP_WAIT_ON_EOS,
 230       g_param_spec_boolean ("wait-on-eos", "Wait on EOS",
 231           "Wait for all buffers to be processed after receiving an EOS",
 232           DEFAULT_PROP_WAIT_ON_EOS,
 233           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 234
 235   /**
 236    * GstAppSink::eos:
 237    * @appsink: the appsink element that emitted the signal
 238    *
 239    * Signal that the end-of-stream has been reached. This signal is emitted from
 240    * the streaming thread.
 241    */
 242   gst_app_sink_signals[SIGNAL_EOS] =
 243       g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 244       G_STRUCT_OFFSET (GstAppSinkClass, eos),
 245       NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
 246   /**
 247    * GstAppSink::new-preroll:
 248    * @appsink: the appsink element that emitted the signal
 249    *
 250    * Signal that a new preroll sample is available.
 251    *
 252    * This signal is emitted from the streaming thread and only when the
 253    * "emit-signals" property is %TRUE.
 254    *
 255    * The new preroll sample can be retrieved with the "pull-preroll" action
 256    * signal or gst_app_sink_pull_preroll() either from this signal callback
 257    * or from any other thread.
 258    *
 259    * Note that this signal is only emitted when the "emit-signals" property is
 260    * set to %TRUE, which it is not by default for performance reasons.
 261    */
 262   gst_app_sink_signals[SIGNAL_NEW_PREROLL] =
 263       g_signal_new ("new-preroll", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 264       G_STRUCT_OFFSET (GstAppSinkClass, new_preroll),
 265       NULL, NULL, NULL, GST_TYPE_FLOW_RETURN, 0, G_TYPE_NONE);
 266   /**
 267    * GstAppSink::new-sample:
 268    * @appsink: the appsink element that emited the signal
 269    *
 270    * Signal that a new sample is available.
 271    *
 272    * This signal is emitted from the streaming thread and only when the
 273    * "emit-signals" property is %TRUE.
 274    *
 275    * The new sample can be retrieved with the "pull-sample" action
 276    * signal or gst_app_sink_pull_sample() either from this signal callback
 277    * or from any other thread.
 278    *
 279    * Note that this signal is only emitted 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_SAMPLE] =
 283       g_signal_new ("new-sample", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 284       G_STRUCT_OFFSET (GstAppSinkClass, new_sample),
 285       NULL, NULL, NULL, GST_TYPE_FLOW_RETURN, 0, G_TYPE_NONE);
 286
 287   /**
 288    * GstAppSink::pull-preroll:
 289    * @appsink: the appsink element to emit this signal on
 290    *
 291    * Get the last preroll sample in @appsink. This was the sample that caused the
 292    * appsink to preroll in the PAUSED state. This sample can be pulled many times
 293    * and remains available to the application even after EOS.
 294    *
 295    * This function is typically used when dealing with a pipeline in the PAUSED
 296    * state. Calling this function after doing a seek will give the sample right
 297    * after the seek position.
 298    *
 299    * Note that the preroll sample will also be returned as the first sample
 300    * when calling gst_app_sink_pull_sample() or the "pull-sample" action signal.
 301    *
 302    * If an EOS event was received before any buffers, this function returns
 303    * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 304    *
 305    * This function blocks until a preroll sample or EOS is received or the appsink
 306    * element is set to the READY/NULL state.
 307    *
 308    * Returns: a #GstSample or NULL when the appsink is stopped or EOS.
 309    */
 310   gst_app_sink_signals[SIGNAL_PULL_PREROLL] =
 311       g_signal_new ("pull-preroll", G_TYPE_FROM_CLASS (klass),
 312       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
 313           pull_preroll), NULL, NULL, NULL, GST_TYPE_SAMPLE, 0, G_TYPE_NONE);
 314   /**
 315    * GstAppSink::pull-sample:
 316    * @appsink: the appsink element to emit this signal on
 317    *
 318    * This function blocks until a sample or EOS becomes available or the appsink
 319    * element is set to the READY/NULL state.
 320    *
 321    * This function will only return samples when the appsink is in the PLAYING
 322    * state. All rendered samples will be put in a queue so that the application
 323    * can pull samples at its own rate.
 324    *
 325    * Note that when the application does not pull samples fast enough, the
 326    * queued samples could consume a lot of memory, especially when dealing with
 327    * raw video frames. It's possible to control the behaviour of the queue with
 328    * the "drop" and "max-buffers" properties.
 329    *
 330    * If an EOS event was received before any buffers, this function returns
 331    * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
 332    *
 333    * Returns: a #GstSample or NULL when the appsink is stopped or EOS.
 334    */
 335   gst_app_sink_signals[SIGNAL_PULL_SAMPLE] =
 336       g_signal_new ("pull-sample", G_TYPE_FROM_CLASS (klass),
 337       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
 338           pull_sample), NULL, NULL, NULL, GST_TYPE_SAMPLE, 0, G_TYPE_NONE);
 339   /**
 340    * GstAppSink::try-pull-preroll:
 341    * @appsink: the appsink element to emit this signal on
 342    * @timeout: the maximum amount of time to wait for the preroll sample
 343    *
 344    * Get the last preroll sample in @appsink. This was the sample that caused the
 345    * appsink to preroll in the PAUSED state. This sample can be pulled many times
 346    * and remains available to the application even after EOS.
 347    *
 348    * This function is typically used when dealing with a pipeline in the PAUSED
 349    * state. Calling this function after doing a seek will give the sample right
 350    * after the seek position.
 351    *
 352    * Note that the preroll sample will also be returned as the first sample
 353    * when calling gst_app_sink_pull_sample() or the "pull-sample" action signal.
 354    *
 355    * If an EOS event was received before any buffers or the timeout expires,
 356    * this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS
 357    * condition.
 358    *
 359    * This function blocks until a preroll sample or EOS is received, the appsink
 360    * element is set to the READY/NULL state, or the timeout expires.
 361    *
 362    * Returns: a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires.
 363    *
 364    * Since: 1.10
 365    */
 366   gst_app_sink_signals[SIGNAL_TRY_PULL_PREROLL] =
 367       g_signal_new ("try-pull-preroll", G_TYPE_FROM_CLASS (klass),
 368       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
 369       G_STRUCT_OFFSET (GstAppSinkClass, try_pull_preroll), NULL, NULL, NULL,
 370       GST_TYPE_SAMPLE, 1, GST_TYPE_CLOCK_TIME);
 371   /**
 372    * GstAppSink::try-pull-sample:
 373    * @appsink: the appsink element to emit this signal on
 374    * @timeout: the maximum amount of time to wait for a sample
 375    *
 376    * This function blocks until a sample or EOS becomes available or the appsink
 377    * element is set to the READY/NULL state or the timeout expires.
 378    *
 379    * This function will only return samples when the appsink is in the PLAYING
 380    * state. All rendered samples will be put in a queue so that the application
 381    * can pull samples at its own rate.
 382    *
 383    * Note that when the application does not pull samples fast enough, the
 384    * queued samples could consume a lot of memory, especially when dealing with
 385    * raw video frames. It's possible to control the behaviour of the queue with
 386    * the "drop" and "max-buffers" properties.
 387    *
 388    * If an EOS event was received before any buffers or the timeout expires,
 389    * this function returns %NULL. Use gst_app_sink_is_eos () to check
 390    * for the EOS condition.
 391    *
 392    * Returns: a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires.
 393    *
 394    * Since: 1.10
 395    */
 396   gst_app_sink_signals[SIGNAL_TRY_PULL_SAMPLE] =
 397       g_signal_new ("try-pull-sample", G_TYPE_FROM_CLASS (klass),
 398       G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
 399       G_STRUCT_OFFSET (GstAppSinkClass, try_pull_sample), NULL, NULL, NULL,
 400       GST_TYPE_SAMPLE, 1, GST_TYPE_CLOCK_TIME);
 401
 402   gst_element_class_set_static_metadata (element_class, "AppSink",
 403       "Generic/Sink", "Allow the application to get access to raw buffer",
 404       "David Schleef <ds@schleef.org>, Wim Taymans <wim.taymans@gmail.com>");
 405
 406   gst_element_class_add_static_pad_template (element_class,
 407       &gst_app_sink_template);
 408
 409   basesink_class->unlock = gst_app_sink_unlock_start;
 410   basesink_class->unlock_stop = gst_app_sink_unlock_stop;
 411   basesink_class->start = gst_app_sink_start;
 412   basesink_class->stop = gst_app_sink_stop;
 413   basesink_class->event = gst_app_sink_event;
 414   basesink_class->preroll = gst_app_sink_preroll;
 415   basesink_class->render = gst_app_sink_render;
 416   basesink_class->get_caps = gst_app_sink_getcaps;
 417   basesink_class->set_caps = gst_app_sink_setcaps;
 418   basesink_class->query = gst_app_sink_query;
 419
 420   klass->pull_preroll = gst_app_sink_pull_preroll;
 421   klass->pull_sample = gst_app_sink_pull_sample;
 422   klass->try_pull_preroll = gst_app_sink_try_pull_preroll;
 423   klass->try_pull_sample = gst_app_sink_try_pull_sample;
 424
 425   g_type_class_add_private (klass, sizeof (GstAppSinkPrivate));
 426 }
 427
 428 static void
 429 gst_app_sink_init (GstAppSink * appsink)
 430 {
 431   GstAppSinkPrivate *priv;
 432
 433   priv = appsink->priv =
 434       G_TYPE_INSTANCE_GET_PRIVATE (appsink, GST_TYPE_APP_SINK,
 435       GstAppSinkPrivate);
 436
 437   g_mutex_init (&priv->mutex);
 438   g_cond_init (&priv->cond);
 439   priv->queue = g_queue_new ();
 440
 441   priv->emit_signals = DEFAULT_PROP_EMIT_SIGNALS;
 442   priv->max_buffers = DEFAULT_PROP_MAX_BUFFERS;
 443   priv->drop = DEFAULT_PROP_DROP;
 444   priv->wait_on_eos = DEFAULT_PROP_WAIT_ON_EOS;
 445 }
 446
 447 static void
 448 gst_app_sink_dispose (GObject * obj)
 449 {
 450   GstAppSink *appsink = GST_APP_SINK_CAST (obj);
 451   GstAppSinkPrivate *priv = appsink->priv;
 452   GstMiniObject *queue_obj;
 453
 454   GST_OBJECT_LOCK (appsink);
 455   if (priv->caps) {
 456     gst_caps_unref (priv->caps);
 457     priv->caps = NULL;
 458   }
 459   if (priv->notify) {
 460     priv->notify (priv->user_data);
 461   }
 462   priv->user_data = NULL;
 463   priv->notify = NULL;
 464
 465   GST_OBJECT_UNLOCK (appsink);
 466
 467   g_mutex_lock (&priv->mutex);
 468   while ((queue_obj = g_queue_pop_head (priv->queue)))
 469     gst_mini_object_unref (queue_obj);
 470   gst_buffer_replace (&priv->preroll, NULL);
 471   gst_caps_replace (&priv->preroll_caps, NULL);
 472   gst_caps_replace (&priv->last_caps, NULL);
 473   g_mutex_unlock (&priv->mutex);
 474
 475   G_OBJECT_CLASS (parent_class)->dispose (obj);
 476 }
 477
 478 static void
 479 gst_app_sink_finalize (GObject * obj)
 480 {
 481   GstAppSink *appsink = GST_APP_SINK_CAST (obj);
 482   GstAppSinkPrivate *priv = appsink->priv;
 483
 484   g_mutex_clear (&priv->mutex);
 485   g_cond_clear (&priv->cond);
 486   g_queue_free (priv->queue);
 487
 488   G_OBJECT_CLASS (parent_class)->finalize (obj);
 489 }
 490
 491 static void
 492 gst_app_sink_set_property (GObject * object, guint prop_id,
 493     const GValue * value, GParamSpec * pspec)
 494 {
 495   GstAppSink *appsink = GST_APP_SINK_CAST (object);
 496
 497   switch (prop_id) {
 498     case PROP_CAPS:
 499       gst_app_sink_set_caps (appsink, gst_value_get_caps (value));
 500       break;
 501     case PROP_EMIT_SIGNALS:
 502       gst_app_sink_set_emit_signals (appsink, g_value_get_boolean (value));
 503       break;
 504     case PROP_MAX_BUFFERS:
 505       gst_app_sink_set_max_buffers (appsink, g_value_get_uint (value));
 506       break;
 507     case PROP_DROP:
 508       gst_app_sink_set_drop (appsink, g_value_get_boolean (value));
 509       break;
 510     case PROP_WAIT_ON_EOS:
 511       gst_app_sink_set_wait_on_eos (appsink, g_value_get_boolean (value));
 512       break;
 513     default:
 514       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 515       break;
 516   }
 517 }
 518
 519 static void
 520 gst_app_sink_get_property (GObject * object, guint prop_id, GValue * value,
 521     GParamSpec * pspec)
 522 {
 523   GstAppSink *appsink = GST_APP_SINK_CAST (object);
 524
 525   switch (prop_id) {
 526     case PROP_CAPS:
 527     {
 528       GstCaps *caps;
 529
 530       caps = gst_app_sink_get_caps (appsink);
 531       gst_value_set_caps (value, caps);
 532       if (caps)
 533         gst_caps_unref (caps);
 534       break;
 535     }
 536     case PROP_EOS:
 537       g_value_set_boolean (value, gst_app_sink_is_eos (appsink));
 538       break;
 539     case PROP_EMIT_SIGNALS:
 540       g_value_set_boolean (value, gst_app_sink_get_emit_signals (appsink));
 541       break;
 542     case PROP_MAX_BUFFERS:
 543       g_value_set_uint (value, gst_app_sink_get_max_buffers (appsink));
 544       break;
 545     case PROP_DROP:
 546       g_value_set_boolean (value, gst_app_sink_get_drop (appsink));
 547       break;
 548     case PROP_WAIT_ON_EOS:
 549       g_value_set_boolean (value, gst_app_sink_get_wait_on_eos (appsink));
 550       break;
 551     default:
 552       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 553       break;
 554   }
 555 }
 556
 557 static gboolean
 558 gst_app_sink_unlock_start (GstBaseSink * bsink)
 559 {
 560   GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
 561   GstAppSinkPrivate *priv = appsink->priv;
 562
 563   g_mutex_lock (&priv->mutex);
 564   GST_DEBUG_OBJECT (appsink, "unlock start");
 565   priv->unlock = TRUE;
 566   g_cond_signal (&priv->cond);
 567   g_mutex_unlock (&priv->mutex);
 568
 569   return TRUE;
 570 }
 571
 572 static gboolean
 573 gst_app_sink_unlock_stop (GstBaseSink * bsink)
 574 {
 575   GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
 576   GstAppSinkPrivate *priv = appsink->priv;
 577
 578   g_mutex_lock (&priv->mutex);
 579   GST_DEBUG_OBJECT (appsink, "unlock stop");
 580   priv->unlock = FALSE;
 581   g_cond_signal (&priv->cond);
 582   g_mutex_unlock (&priv->mutex);
 583
 584   return TRUE;
 585 }
 586
 587 static void
 588 gst_app_sink_flush_unlocked (GstAppSink * appsink)
 589 {
 590   GstMiniObject *obj;
 591   GstAppSinkPrivate *priv = appsink->priv;
 592
 593   GST_DEBUG_OBJECT (appsink, "flush stop appsink");
 594   priv->is_eos = FALSE;
 595   gst_buffer_replace (&priv->preroll, NULL);
 596   while ((obj = g_queue_pop_head (priv->queue)))
 597     gst_mini_object_unref (obj);
 598   priv->num_buffers = 0;
 599   g_cond_signal (&priv->cond);
 600 }
 601
 602 static gboolean
 603 gst_app_sink_start (GstBaseSink * psink)
 604 {
 605   GstAppSink *appsink = GST_APP_SINK_CAST (psink);
 606   GstAppSinkPrivate *priv = appsink->priv;
 607
 608   g_mutex_lock (&priv->mutex);
 609   GST_DEBUG_OBJECT (appsink, "starting");
 610   priv->flushing = FALSE;
 611   priv->started = TRUE;
 612   gst_segment_init (&priv->preroll_segment, GST_FORMAT_TIME);
 613   gst_segment_init (&priv->last_segment, GST_FORMAT_TIME);
 614   g_mutex_unlock (&priv->mutex);
 615
 616   return TRUE;
 617 }
 618
 619 static gboolean
 620 gst_app_sink_stop (GstBaseSink * psink)
 621 {
 622   GstAppSink *appsink = GST_APP_SINK_CAST (psink);
 623   GstAppSinkPrivate *priv = appsink->priv;
 624
 625   g_mutex_lock (&priv->mutex);
 626   GST_DEBUG_OBJECT (appsink, "stopping");
 627   priv->flushing = TRUE;
 628   priv->started = FALSE;
 629   gst_app_sink_flush_unlocked (appsink);
 630   gst_buffer_replace (&priv->preroll, NULL);
 631   gst_caps_replace (&priv->preroll_caps, NULL);
 632   gst_caps_replace (&priv->last_caps, NULL);
 633   gst_segment_init (&priv->preroll_segment, GST_FORMAT_UNDEFINED);
 634   gst_segment_init (&priv->last_segment, GST_FORMAT_UNDEFINED);
 635   g_mutex_unlock (&priv->mutex);
 636
 637   return TRUE;
 638 }
 639
 640 static gboolean
 641 gst_app_sink_setcaps (GstBaseSink * sink, GstCaps * caps)
 642 {
 643   GstAppSink *appsink = GST_APP_SINK_CAST (sink);
 644   GstAppSinkPrivate *priv = appsink->priv;
 645
 646   g_mutex_lock (&priv->mutex);
 647   GST_DEBUG_OBJECT (appsink, "receiving CAPS");
 648   g_queue_push_tail (priv->queue, gst_event_new_caps (caps));
 649   if (!priv->preroll)
 650     gst_caps_replace (&priv->preroll_caps, caps);
 651   g_mutex_unlock (&priv->mutex);
 652
 653   return TRUE;
 654 }
 655
 656 static gboolean
 657 gst_app_sink_event (GstBaseSink * sink, GstEvent * event)
 658 {
 659   GstAppSink *appsink = GST_APP_SINK_CAST (sink);
 660   GstAppSinkPrivate *priv = appsink->priv;
 661
 662   switch (event->type) {
 663     case GST_EVENT_SEGMENT:
 664       g_mutex_lock (&priv->mutex);
 665       GST_DEBUG_OBJECT (appsink, "receiving SEGMENT");
 666       g_queue_push_tail (priv->queue, gst_event_ref (event));
 667       if (!priv->preroll)
 668         gst_event_copy_segment (event, &priv->preroll_segment);
 669       g_mutex_unlock (&priv->mutex);
 670       break;
 671     case GST_EVENT_EOS:{
 672       gboolean emit = TRUE;
 673
 674       g_mutex_lock (&priv->mutex);
 675       GST_DEBUG_OBJECT (appsink, "receiving EOS");
 676       priv->is_eos = TRUE;
 677       g_cond_signal (&priv->cond);
 678       g_mutex_unlock (&priv->mutex);
 679
 680       g_mutex_lock (&priv->mutex);
 681       /* wait until all buffers are consumed or we're flushing.
 682        * Otherwise we might signal EOS before all buffers are
 683        * consumed, which is a bit confusing for the application
 684        */
 685       while (priv->num_buffers > 0 && !priv->flushing && priv->wait_on_eos)
 686         g_cond_wait (&priv->cond, &priv->mutex);
 687       if (priv->flushing)
 688         emit = FALSE;
 689       g_mutex_unlock (&priv->mutex);
 690
 691       if (emit) {
 692         /* emit EOS now */
 693         if (priv->callbacks.eos)
 694           priv->callbacks.eos (appsink, priv->user_data);
 695         else
 696           g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_EOS], 0);
 697       }
 698
 699       break;
 700     }
 701     case GST_EVENT_FLUSH_START:
 702       /* we don't have to do anything here, the base class will call unlock
 703        * which will make sure we exit the _render method */
 704       GST_DEBUG_OBJECT (appsink, "received FLUSH_START");
 705       break;
 706     case GST_EVENT_FLUSH_STOP:
 707       g_mutex_lock (&priv->mutex);
 708       GST_DEBUG_OBJECT (appsink, "received FLUSH_STOP");
 709       gst_app_sink_flush_unlocked (appsink);
 710       g_mutex_unlock (&priv->mutex);
 711       break;
 712     default:
 713       break;
 714   }
 715   return GST_BASE_SINK_CLASS (parent_class)->event (sink, event);
 716 }
 717
 718 static GstFlowReturn
 719 gst_app_sink_preroll (GstBaseSink * psink, GstBuffer * buffer)
 720 {
 721   GstFlowReturn res;
 722   GstAppSink *appsink = GST_APP_SINK_CAST (psink);
 723   GstAppSinkPrivate *priv = appsink->priv;
 724   gboolean emit;
 725
 726   g_mutex_lock (&priv->mutex);
 727   if (priv->flushing)
 728     goto flushing;
 729
 730   GST_DEBUG_OBJECT (appsink, "setting preroll buffer %p", buffer);
 731   gst_buffer_replace (&priv->preroll, buffer);
 732
 733   g_cond_signal (&priv->cond);
 734   emit = priv->emit_signals;
 735   g_mutex_unlock (&priv->mutex);
 736
 737   if (priv->callbacks.new_preroll) {
 738     res = priv->callbacks.new_preroll (appsink, priv->user_data);
 739   } else {
 740     res = GST_FLOW_OK;
 741     if (emit)
 742       g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_PREROLL], 0,
 743           &res);
 744   }
 745
 746   return res;
 747
 748 flushing:
 749   {
 750     GST_DEBUG_OBJECT (appsink, "we are flushing");
 751     g_mutex_unlock (&priv->mutex);
 752     return GST_FLOW_FLUSHING;
 753   }
 754 }
 755
 756 static GstBuffer *
 757 dequeue_buffer (GstAppSink * appsink)
 758 {
 759   GstAppSinkPrivate *priv = appsink->priv;
 760   GstBuffer *buffer;
 761
 762   do {
 763     GstMiniObject *obj;
 764
 765     obj = g_queue_pop_head (priv->queue);
 766
 767     if (GST_IS_BUFFER (obj)) {
 768       buffer = GST_BUFFER_CAST (obj);
 769       GST_DEBUG_OBJECT (appsink, "dequeued buffer %p", buffer);
 770       priv->num_buffers--;
 771       break;
 772     } else if (GST_IS_EVENT (obj)) {
 773       GstEvent *event = GST_EVENT_CAST (obj);
 774
 775       switch (GST_EVENT_TYPE (obj)) {
 776         case GST_EVENT_CAPS:
 777         {
 778           GstCaps *caps;
 779
 780           gst_event_parse_caps (event, &caps);
 781           GST_DEBUG_OBJECT (appsink, "activating caps %" GST_PTR_FORMAT, caps);
 782           gst_caps_replace (&priv->last_caps, caps);
 783           break;
 784         }
 785         case GST_EVENT_SEGMENT:
 786           gst_event_copy_segment (event, &priv->last_segment);
 787           GST_DEBUG_OBJECT (appsink, "activated segment %" GST_SEGMENT_FORMAT,
 788               &priv->last_segment);
 789           break;
 790         default:
 791           break;
 792       }
 793       gst_mini_object_unref (obj);
 794     }
 795   } while (TRUE);
 796
 797   return buffer;
 798 }
 799
 800 static GstFlowReturn
 801 gst_app_sink_render (GstBaseSink * psink, GstBuffer * buffer)
 802 {
 803   GstFlowReturn ret;
 804   GstAppSink *appsink = GST_APP_SINK_CAST (psink);
 805   GstAppSinkPrivate *priv = appsink->priv;
 806   gboolean emit;
 807
 808 restart:
 809   g_mutex_lock (&priv->mutex);
 810   if (priv->flushing)
 811     goto flushing;
 812
 813   /* queue holding caps event might have been FLUSHed,
 814    * but caps state still present in pad caps */
 815   if (G_UNLIKELY (!priv->last_caps &&
 816           gst_pad_has_current_caps (GST_BASE_SINK_PAD (psink)))) {
 817     priv->last_caps = gst_pad_get_current_caps (GST_BASE_SINK_PAD (psink));
 818     GST_DEBUG_OBJECT (appsink, "activating pad caps %" GST_PTR_FORMAT,
 819         priv->last_caps);
 820   }
 821
 822   GST_DEBUG_OBJECT (appsink, "pushing render buffer %p on queue (%d)",
 823       buffer, priv->num_buffers);
 824
 825   while (priv->max_buffers > 0 && priv->num_buffers >= priv->max_buffers) {
 826     if (priv->drop) {
 827       GstBuffer *old;
 828
 829       /* we need to drop the oldest buffer and try again */
 830       if ((old = dequeue_buffer (appsink))) {
 831         GST_DEBUG_OBJECT (appsink, "dropping old buffer %p", old);
 832         gst_buffer_unref (old);
 833       }
 834     } else {
 835       GST_DEBUG_OBJECT (appsink, "waiting for free space, length %d >= %d",
 836           priv->num_buffers, priv->max_buffers);
 837
 838       if (priv->unlock) {
 839         /* we are asked to unlock, call the wait_preroll method */
 840         g_mutex_unlock (&priv->mutex);
 841         if ((ret = gst_base_sink_wait_preroll (psink)) != GST_FLOW_OK)
 842           goto stopping;
 843
 844         /* we are allowed to continue now */
 845         goto restart;
 846       }
 847
 848       /* wait for a buffer to be removed or flush */
 849       g_cond_wait (&priv->cond, &priv->mutex);
 850       if (priv->flushing)
 851         goto flushing;
 852     }
 853   }
 854   /* we need to ref the buffer when pushing it in the queue */
 855   g_queue_push_tail (priv->queue, gst_buffer_ref (buffer));
 856   priv->num_buffers++;
 857   g_cond_signal (&priv->cond);
 858   emit = priv->emit_signals;
 859   g_mutex_unlock (&priv->mutex);
 860
 861   if (priv->callbacks.new_sample) {
 862     ret = priv->callbacks.new_sample (appsink, priv->user_data);
 863   } else {
 864     ret = GST_FLOW_OK;
 865     if (emit)
 866       g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_SAMPLE], 0, &ret);
 867   }
 868   return ret;
 869
 870 flushing:
 871   {
 872     GST_DEBUG_OBJECT (appsink, "we are flushing");
 873     g_mutex_unlock (&priv->mutex);
 874     return GST_FLOW_FLUSHING;
 875   }
 876 stopping:
 877   {
 878     GST_DEBUG_OBJECT (appsink, "we are stopping");
 879     return ret;
 880   }
 881 }
 882
 883 static GstCaps *
 884 gst_app_sink_getcaps (GstBaseSink * psink, GstCaps * filter)
 885 {
 886   GstCaps *caps;
 887   GstAppSink *appsink = GST_APP_SINK_CAST (psink);
 888   GstAppSinkPrivate *priv = appsink->priv;
 889
 890   GST_OBJECT_LOCK (appsink);
 891   if ((caps = priv->caps)) {
 892     if (filter)
 893       caps = gst_caps_intersect_full (filter, caps, GST_CAPS_INTERSECT_FIRST);
 894     else
 895       gst_caps_ref (caps);
 896   }
 897   GST_DEBUG_OBJECT (appsink, "got caps %" GST_PTR_FORMAT, caps);
 898   GST_OBJECT_UNLOCK (appsink);
 899
 900   return caps;
 901 }
 902
 903 static gboolean
 904 gst_app_sink_query (GstBaseSink * bsink, GstQuery * query)
 905 {
 906   gboolean ret;
 907
 908   switch (GST_QUERY_TYPE (query)) {
 909     case GST_QUERY_SEEKING:{
 910       GstFormat fmt;
 911
 912       /* we don't supporting seeking */
 913       gst_query_parse_seeking (query, &fmt, NULL, NULL, NULL);
 914       gst_query_set_seeking (query, fmt, FALSE, 0, -1);
 915       ret = TRUE;
 916       break;
 917     }
 918
 919     default:
 920       ret = GST_BASE_SINK_CLASS (parent_class)->query (bsink, query);
 921       break;
 922   }
 923
 924   return ret;
 925 }
 926
 927 /* external API */
 928
 929 /**
 930  * gst_app_sink_set_caps:
 931  * @appsink: a #GstAppSink
 932  * @caps: caps to set
 933  *
 934  * Set the capabilities on the appsink element.  This function takes
 935  * a copy of the caps structure. After calling this method, the sink will only
 936  * accept caps that match @caps. If @caps is non-fixed, or incomplete,
 937  * you must check the caps on the samples to get the actual used caps.
 938  */
 939 void
 940 gst_app_sink_set_caps (GstAppSink * appsink, const GstCaps * caps)
 941 {
 942   GstCaps *old;
 943   GstAppSinkPrivate *priv;
 944
 945   g_return_if_fail (GST_IS_APP_SINK (appsink));
 946
 947   priv = appsink->priv;
 948
 949   GST_OBJECT_LOCK (appsink);
 950   GST_DEBUG_OBJECT (appsink, "setting caps to %" GST_PTR_FORMAT, caps);
 951   if ((old = priv->caps) != caps) {
 952     if (caps)
 953       priv->caps = gst_caps_copy (caps);
 954     else
 955       priv->caps = NULL;
 956     if (old)
 957       gst_caps_unref (old);
 958   }
 959   GST_OBJECT_UNLOCK (appsink);
 960 }
 961
 962 /**
 963  * gst_app_sink_get_caps:
 964  * @appsink: a #GstAppSink
 965  *
 966  * Get the configured caps on @appsink.
 967  *
 968  * Returns: the #GstCaps accepted by the sink. gst_caps_unref() after usage.
 969  */
 970 GstCaps *
 971 gst_app_sink_get_caps (GstAppSink * appsink)
 972 {
 973   GstCaps *caps;
 974   GstAppSinkPrivate *priv;
 975
 976   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
 977
 978   priv = appsink->priv;
 979
 980   GST_OBJECT_LOCK (appsink);
 981   if ((caps = priv->caps))
 982     gst_caps_ref (caps);
 983   GST_DEBUG_OBJECT (appsink, "getting caps of %" GST_PTR_FORMAT, caps);
 984   GST_OBJECT_UNLOCK (appsink);
 985
 986   return caps;
 987 }
 988
 989 /**
 990  * gst_app_sink_is_eos:
 991  * @appsink: a #GstAppSink
 992  *
 993  * Check if @appsink is EOS, which is when no more samples can be pulled because
 994  * an EOS event was received.
 995  *
 996  * This function also returns %TRUE when the appsink is not in the PAUSED or
 997  * PLAYING state.
 998  *
 999  * Returns: %TRUE if no more samples can be pulled and the appsink is EOS.
1000  */
1001 gboolean
1002 gst_app_sink_is_eos (GstAppSink * appsink)
1003 {
1004   gboolean ret;
1005   GstAppSinkPrivate *priv;
1006
1007   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1008
1009   priv = appsink->priv;
1010
1011   g_mutex_lock (&priv->mutex);
1012   if (!priv->started)
1013     goto not_started;
1014
1015   if (priv->is_eos && priv->num_buffers == 0) {
1016     GST_DEBUG_OBJECT (appsink, "we are EOS and the queue is empty");
1017     ret = TRUE;
1018   } else {
1019     GST_DEBUG_OBJECT (appsink, "we are not yet EOS");
1020     ret = FALSE;
1021   }
1022   g_mutex_unlock (&priv->mutex);
1023
1024   return ret;
1025
1026 not_started:
1027   {
1028     GST_DEBUG_OBJECT (appsink, "we are stopped, return TRUE");
1029     g_mutex_unlock (&priv->mutex);
1030     return TRUE;
1031   }
1032 }
1033
1034 /**
1035  * gst_app_sink_set_emit_signals:
1036  * @appsink: a #GstAppSink
1037  * @emit: the new state
1038  *
1039  * Make appsink emit the "new-preroll" and "new-sample" signals. This option is
1040  * by default disabled because signal emission is expensive and unneeded when
1041  * the application prefers to operate in pull mode.
1042  */
1043 void
1044 gst_app_sink_set_emit_signals (GstAppSink * appsink, gboolean emit)
1045 {
1046   GstAppSinkPrivate *priv;
1047
1048   g_return_if_fail (GST_IS_APP_SINK (appsink));
1049
1050   priv = appsink->priv;
1051
1052   g_mutex_lock (&priv->mutex);
1053   priv->emit_signals = emit;
1054   g_mutex_unlock (&priv->mutex);
1055 }
1056
1057 /**
1058  * gst_app_sink_get_emit_signals:
1059  * @appsink: a #GstAppSink
1060  *
1061  * Check if appsink will emit the "new-preroll" and "new-sample" signals.
1062  *
1063  * Returns: %TRUE if @appsink is emiting the "new-preroll" and "new-sample"
1064  * signals.
1065  */
1066 gboolean
1067 gst_app_sink_get_emit_signals (GstAppSink * appsink)
1068 {
1069   gboolean result;
1070   GstAppSinkPrivate *priv;
1071
1072   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1073
1074   priv = appsink->priv;
1075
1076   g_mutex_lock (&priv->mutex);
1077   result = priv->emit_signals;
1078   g_mutex_unlock (&priv->mutex);
1079
1080   return result;
1081 }
1082
1083 /**
1084  * gst_app_sink_set_max_buffers:
1085  * @appsink: a #GstAppSink
1086  * @max: the maximum number of buffers to queue
1087  *
1088  * Set the maximum amount of buffers that can be queued in @appsink. After this
1089  * amount of buffers are queued in appsink, any more buffers will block upstream
1090  * elements until a sample is pulled from @appsink.
1091  */
1092 void
1093 gst_app_sink_set_max_buffers (GstAppSink * appsink, guint max)
1094 {
1095   GstAppSinkPrivate *priv;
1096
1097   g_return_if_fail (GST_IS_APP_SINK (appsink));
1098
1099   priv = appsink->priv;
1100
1101   g_mutex_lock (&priv->mutex);
1102   if (max != priv->max_buffers) {
1103     priv->max_buffers = max;
1104     /* signal the change */
1105     g_cond_signal (&priv->cond);
1106   }
1107   g_mutex_unlock (&priv->mutex);
1108 }
1109
1110 /**
1111  * gst_app_sink_get_max_buffers:
1112  * @appsink: a #GstAppSink
1113  *
1114  * Get the maximum amount of buffers that can be queued in @appsink.
1115  *
1116  * Returns: The maximum amount of buffers that can be queued.
1117  */
1118 guint
1119 gst_app_sink_get_max_buffers (GstAppSink * appsink)
1120 {
1121   guint result;
1122   GstAppSinkPrivate *priv;
1123
1124   g_return_val_if_fail (GST_IS_APP_SINK (appsink), 0);
1125
1126   priv = appsink->priv;
1127
1128   g_mutex_lock (&priv->mutex);
1129   result = priv->max_buffers;
1130   g_mutex_unlock (&priv->mutex);
1131
1132   return result;
1133 }
1134
1135 /**
1136  * gst_app_sink_set_drop:
1137  * @appsink: a #GstAppSink
1138  * @drop: the new state
1139  *
1140  * Instruct @appsink to drop old buffers when the maximum amount of queued
1141  * buffers is reached.
1142  */
1143 void
1144 gst_app_sink_set_drop (GstAppSink * appsink, gboolean drop)
1145 {
1146   GstAppSinkPrivate *priv;
1147
1148   g_return_if_fail (GST_IS_APP_SINK (appsink));
1149
1150   priv = appsink->priv;
1151
1152   g_mutex_lock (&priv->mutex);
1153   if (priv->drop != drop) {
1154     priv->drop = drop;
1155     /* signal the change */
1156     g_cond_signal (&priv->cond);
1157   }
1158   g_mutex_unlock (&priv->mutex);
1159 }
1160
1161 /**
1162  * gst_app_sink_get_drop:
1163  * @appsink: a #GstAppSink
1164  *
1165  * Check if @appsink will drop old buffers when the maximum amount of queued
1166  * buffers is reached.
1167  *
1168  * Returns: %TRUE if @appsink is dropping old buffers when the queue is
1169  * filled.
1170  */
1171 gboolean
1172 gst_app_sink_get_drop (GstAppSink * appsink)
1173 {
1174   gboolean result;
1175   GstAppSinkPrivate *priv;
1176
1177   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1178
1179   priv = appsink->priv;
1180
1181   g_mutex_lock (&priv->mutex);
1182   result = priv->drop;
1183   g_mutex_unlock (&priv->mutex);
1184
1185   return result;
1186 }
1187
1188 /**
1189  * gst_app_sink_set_wait_on_eos:
1190  * @appsink: a #GstAppSink
1191  * @wait: the new state
1192  *
1193  * Instruct @appsink to wait for all buffers to be consumed when an EOS is received.
1194  *
1195  */
1196 void
1197 gst_app_sink_set_wait_on_eos (GstAppSink * appsink, gboolean wait)
1198 {
1199   GstAppSinkPrivate *priv;
1200
1201   g_return_if_fail (GST_IS_APP_SINK (appsink));
1202
1203   priv = appsink->priv;
1204
1205   g_mutex_lock (&priv->mutex);
1206   if (priv->wait_on_eos != wait) {
1207     priv->wait_on_eos = wait;
1208     /* signal the change */
1209     g_cond_signal (&priv->cond);
1210   }
1211   g_mutex_unlock (&priv->mutex);
1212 }
1213
1214 /**
1215  * gst_app_sink_get_wait_on_eos:
1216  * @appsink: a #GstAppSink
1217  *
1218  * Check if @appsink will wait for all buffers to be consumed when an EOS is
1219  * received.
1220  *
1221  * Returns: %TRUE if @appsink will wait for all buffers to be consumed when an
1222  * EOS is received.
1223  */
1224 gboolean
1225 gst_app_sink_get_wait_on_eos (GstAppSink * appsink)
1226 {
1227   gboolean result;
1228   GstAppSinkPrivate *priv;
1229
1230   g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1231
1232   priv = appsink->priv;
1233
1234   g_mutex_lock (&priv->mutex);
1235   result = priv->wait_on_eos;
1236   g_mutex_unlock (&priv->mutex);
1237
1238   return result;
1239 }
1240
1241 /**
1242  * gst_app_sink_pull_preroll:
1243  * @appsink: a #GstAppSink
1244  *
1245  * Get the last preroll sample in @appsink. This was the sample that caused the
1246  * appsink to preroll in the PAUSED state. This sample can be pulled many times
1247  * and remains available to the application even after EOS.
1248  *
1249  * This function is typically used when dealing with a pipeline in the PAUSED
1250  * state. Calling this function after doing a seek will give the sample right
1251  * after the seek position.
1252  *
1253  * Note that the preroll sample will also be returned as the first sample
1254  * when calling gst_app_sink_pull_sample().
1255  *
1256  * If an EOS event was received before any buffers, this function returns
1257  * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1258  *
1259  * This function blocks until a preroll sample or EOS is received or the appsink
1260  * element is set to the READY/NULL state.
1261  *
1262  * Returns: (transfer full): a #GstSample or NULL when the appsink is stopped or EOS.
1263  *          Call gst_sample_unref() after usage.
1264  */
1265 GstSample *
1266 gst_app_sink_pull_preroll (GstAppSink * appsink)
1267 {
1268   return gst_app_sink_try_pull_preroll (appsink, GST_CLOCK_TIME_NONE);
1269 }
1270
1271 /**
1272  * gst_app_sink_pull_sample:
1273  * @appsink: a #GstAppSink
1274  *
1275  * This function blocks until a sample or EOS becomes available or the appsink
1276  * element is set to the READY/NULL state.
1277  *
1278  * This function will only return samples when the appsink is in the PLAYING
1279  * state. All rendered buffers will be put in a queue so that the application
1280  * can pull samples at its own rate. Note that when the application does not
1281  * pull samples fast enough, the queued buffers could consume a lot of memory,
1282  * especially when dealing with raw video frames.
1283  *
1284  * If an EOS event was received before any buffers, this function returns
1285  * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1286  *
1287  * Returns: (transfer full): a #GstSample or NULL when the appsink is stopped or EOS.
1288  *          Call gst_sample_unref() after usage.
1289  */
1290 GstSample *
1291 gst_app_sink_pull_sample (GstAppSink * appsink)
1292 {
1293   return gst_app_sink_try_pull_sample (appsink, GST_CLOCK_TIME_NONE);
1294 }
1295
1296 /**
1297  * gst_app_sink_try_pull_preroll:
1298  * @appsink: a #GstAppSink
1299  * @timeout: the maximum amount of time to wait for the preroll sample
1300  *
1301  * Get the last preroll sample in @appsink. This was the sample that caused the
1302  * appsink to preroll in the PAUSED state. This sample can be pulled many times
1303  * and remains available to the application even after EOS.
1304  *
1305  * This function is typically used when dealing with a pipeline in the PAUSED
1306  * state. Calling this function after doing a seek will give the sample right
1307  * after the seek position.
1308  *
1309  * Note that the preroll sample will also be returned as the first sample
1310  * when calling gst_app_sink_pull_sample().
1311  *
1312  * If an EOS event was received before any buffers or the timeout expires,
1313  * this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS
1314  * condition.
1315  *
1316  * This function blocks until a preroll sample or EOS is received, the appsink
1317  * element is set to the READY/NULL state, or the timeout expires.
1318  *
1319  * Returns: (transfer full): a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires.
1320  *          Call gst_sample_unref() after usage.
1321  *
1322  * Since: 1.10
1323  */
1324 GstSample *
1325 gst_app_sink_try_pull_preroll (GstAppSink * appsink, GstClockTime timeout)
1326 {
1327   GstAppSinkPrivate *priv;
1328   GstSample *sample = NULL;
1329   gboolean timeout_valid;
1330   gint64 end_time;
1331
1332   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
1333
1334   priv = appsink->priv;
1335
1336   timeout_valid = GST_CLOCK_TIME_IS_VALID (timeout);
1337
1338   if (timeout_valid)
1339     end_time =
1340         g_get_monotonic_time () + timeout / (GST_SECOND / G_TIME_SPAN_SECOND);
1341
1342   g_mutex_lock (&priv->mutex);
1343
1344   while (TRUE) {
1345     GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
1346     if (!priv->started)
1347       goto not_started;
1348
1349     if (priv->preroll != NULL)
1350       break;
1351
1352     if (priv->is_eos)
1353       goto eos;
1354
1355     /* nothing to return, wait */
1356     GST_DEBUG_OBJECT (appsink, "waiting for the preroll buffer");
1357     if (timeout_valid) {
1358       if (!g_cond_wait_until (&priv->cond, &priv->mutex, end_time))
1359         goto expired;
1360     } else {
1361       g_cond_wait (&priv->cond, &priv->mutex);
1362     }
1363   }
1364   sample =
1365       gst_sample_new (priv->preroll, priv->preroll_caps, &priv->preroll_segment,
1366       NULL);
1367   GST_DEBUG_OBJECT (appsink, "we have the preroll sample %p", sample);
1368   g_mutex_unlock (&priv->mutex);
1369
1370   return sample;
1371
1372   /* special conditions */
1373 expired:
1374   {
1375     GST_DEBUG_OBJECT (appsink, "timeout expired, return NULL");
1376     g_mutex_unlock (&priv->mutex);
1377     return NULL;
1378   }
1379 eos:
1380   {
1381     GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
1382     g_mutex_unlock (&priv->mutex);
1383     return NULL;
1384   }
1385 not_started:
1386   {
1387     GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
1388     g_mutex_unlock (&priv->mutex);
1389     return NULL;
1390   }
1391 }
1392
1393 /**
1394  * gst_app_sink_try_pull_sample:
1395  * @appsink: a #GstAppSink
1396  * @timeout: the maximum amount of time to wait for a sample
1397  *
1398  * This function blocks until a sample or EOS becomes available or the appsink
1399  * element is set to the READY/NULL state or the timeout expires.
1400  *
1401  * This function will only return samples when the appsink is in the PLAYING
1402  * state. All rendered buffers will be put in a queue so that the application
1403  * can pull samples at its own rate. Note that when the application does not
1404  * pull samples fast enough, the queued buffers could consume a lot of memory,
1405  * especially when dealing with raw video frames.
1406  *
1407  * If an EOS event was received before any buffers or the timeout expires,
1408  * this function returns %NULL. Use gst_app_sink_is_eos () to check for the EOS
1409  * condition.
1410  *
1411  * Returns: (transfer full): a #GstSample or NULL when the appsink is stopped or EOS or the timeout expires.
1412  * Call gst_sample_unref() after usage.
1413  *
1414  * Since: 1.10
1415  */
1416 GstSample *
1417 gst_app_sink_try_pull_sample (GstAppSink * appsink, GstClockTime timeout)
1418 {
1419   GstAppSinkPrivate *priv;
1420   GstSample *sample = NULL;
1421   GstBuffer *buffer;
1422   gboolean timeout_valid;
1423   gint64 end_time;
1424
1425   g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
1426
1427   timeout_valid = GST_CLOCK_TIME_IS_VALID (timeout);
1428
1429   if (timeout_valid)
1430     end_time =
1431         g_get_monotonic_time () + timeout / (GST_SECOND / G_TIME_SPAN_SECOND);
1432
1433   priv = appsink->priv;
1434
1435   g_mutex_lock (&priv->mutex);
1436
1437   while (TRUE) {
1438     GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
1439     if (!priv->started)
1440       goto not_started;
1441
1442     if (priv->num_buffers > 0)
1443       break;
1444
1445     if (priv->is_eos)
1446       goto eos;
1447
1448     /* nothing to return, wait */
1449     GST_DEBUG_OBJECT (appsink, "waiting for a buffer");
1450     if (timeout_valid) {
1451       if (!g_cond_wait_until (&priv->cond, &priv->mutex, end_time))
1452         goto expired;
1453     } else {
1454       g_cond_wait (&priv->cond, &priv->mutex);
1455     }
1456   }
1457   buffer = dequeue_buffer (appsink);
1458   GST_DEBUG_OBJECT (appsink, "we have a buffer %p", buffer);
1459   sample = gst_sample_new (buffer, priv->last_caps, &priv->last_segment, NULL);
1460   gst_buffer_unref (buffer);
1461
1462   g_cond_signal (&priv->cond);
1463   g_mutex_unlock (&priv->mutex);
1464
1465   return sample;
1466
1467   /* special conditions */
1468 expired:
1469   {
1470     GST_DEBUG_OBJECT (appsink, "timeout expired, return NULL");
1471     g_mutex_unlock (&priv->mutex);
1472     return NULL;
1473   }
1474 eos:
1475   {
1476     GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
1477     g_mutex_unlock (&priv->mutex);
1478     return NULL;
1479   }
1480 not_started:
1481   {
1482     GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
1483     g_mutex_unlock (&priv->mutex);
1484     return NULL;
1485   }
1486 }
1487
1488 /**
1489  * gst_app_sink_set_callbacks: (skip)
1490  * @appsink: a #GstAppSink
1491  * @callbacks: the callbacks
1492  * @user_data: a user_data argument for the callbacks
1493  * @notify: a destroy notify function
1494  *
1495  * Set callbacks which will be executed for each new preroll, new sample and eos.
1496  * This is an alternative to using the signals, it has lower overhead and is thus
1497  * less expensive, but also less flexible.
1498  *
1499  * If callbacks are installed, no signals will be emitted for performance
1500  * reasons.
1501  */
1502 void
1503 gst_app_sink_set_callbacks (GstAppSink * appsink,
1504     GstAppSinkCallbacks * callbacks, gpointer user_data, GDestroyNotify notify)
1505 {
1506   GDestroyNotify old_notify;
1507   GstAppSinkPrivate *priv;
1508
1509   g_return_if_fail (GST_IS_APP_SINK (appsink));
1510   g_return_if_fail (callbacks != NULL);
1511
1512   priv = appsink->priv;
1513
1514   GST_OBJECT_LOCK (appsink);
1515   old_notify = priv->notify;
1516
1517   if (old_notify) {
1518     gpointer old_data;
1519
1520     old_data = priv->user_data;
1521
1522     priv->user_data = NULL;
1523     priv->notify = NULL;
1524     GST_OBJECT_UNLOCK (appsink);
1525
1526     old_notify (old_data);
1527
1528     GST_OBJECT_LOCK (appsink);
1529   }
1530   priv->callbacks = *callbacks;
1531   priv->user_data = user_data;
1532   priv->notify = notify;
1533   GST_OBJECT_UNLOCK (appsink);
1534 }
1535
1536 /*** GSTURIHANDLER INTERFACE *************************************************/
1537
1538 static GstURIType
1539 gst_app_sink_uri_get_type (GType type)
1540 {
1541   return GST_URI_SINK;
1542 }
1543
1544 static const gchar *const *
1545 gst_app_sink_uri_get_protocols (GType type)
1546 {
1547   static const gchar *protocols[] = { "appsink", NULL };
1548
1549   return protocols;
1550 }
1551
1552 static gchar *
1553 gst_app_sink_uri_get_uri (GstURIHandler * handler)
1554 {
1555   return g_strdup ("appsink");
1556 }
1557
1558 static gboolean
1559 gst_app_sink_uri_set_uri (GstURIHandler * handler, const gchar * uri,
1560     GError ** error)
1561 {
1562   /* GstURIHandler checks the protocol for us */
1563   return TRUE;
1564 }
1565
1566 static void
1567 gst_app_sink_uri_handler_init (gpointer g_iface, gpointer iface_data)
1568 {
1569   GstURIHandlerInterface *iface = (GstURIHandlerInterface *) g_iface;
1570
1571   iface->get_type = gst_app_sink_uri_get_type;
1572   iface->get_protocols = gst_app_sink_uri_get_protocols;
1573   iface->get_uri = gst_app_sink_uri_get_uri;
1574   iface->set_uri = gst_app_sink_uri_set_uri;
1575
1576 }