2 * Copyright (C) 2007 David Schleef <ds@schleef.org>
3 * (C) 2008 Wim Taymans <wim.taymans@gmail.com>
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.
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.
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.
22 * SECTION:element-appsink
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.
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.
38 * @short_description: Easy way for applications to extract buffers from a
40 * @see_also: #GstBaseSink, appsrc
42 * Appsink is a sink plugin that supports many different methods for making
43 * the application get a handle on the GStreamer data in a pipeline. Unlike
44 * most GStreamer elements, Appsink provides external API functions.
46 * appsink can be used by linking to the gstappsink.h header file to access the
47 * methods or by using the appsink action signals and properties.
49 * The normal way of retrieving buffers from appsink is by using the
50 * gst_app_sink_pull_buffer() and gst_app_sink_pull_preroll() methods.
51 * These methods block until a buffer becomes available in the sink or when the
52 * sink is shut down or reaches EOS.
54 * Appsink will internally use a queue to collect buffers from the streaming
55 * thread. If the application is not pulling buffers fast enough, this queue
56 * will consume a lot of memory over time. The "max-buffers" property can be
57 * used to limit the queue size. The "drop" property controls whether the
58 * streaming thread blocks or if older buffers are dropped when the maximum
59 * queue size is reached. Note that blocking the streaming thread can negatively
60 * affect real-time performance and should be avoided.
62 * If a blocking behaviour is not desirable, setting the "emit-signals" property
63 * to %TRUE will make appsink emit the "new-buffer" and "new-preroll" signals
64 * when a buffer can be pulled without blocking.
66 * The "caps" property on appsink can be used to control the formats that
67 * appsink can receive. This property can contain non-fixed caps, the format of
68 * the pulled buffers can be obtained by getting the buffer caps.
70 * If one of the pull-preroll or pull-buffer methods return %NULL, the appsink
71 * is stopped or in the EOS state. You can check for the EOS state with the
72 * "eos" property or with the gst_app_sink_is_eos() method.
74 * The eos signal can also be used to be informed when the EOS state is reached
77 * Last reviewed on 2008-12-17 (0.10.22)
87 #include <gst/base/gstbasesink.h>
88 #include <gst/gstbuffer.h>
89 #include <gst/gstbufferlist.h>
93 #include "gstappsink.h"
95 struct _GstAppSinkPrivate
98 gboolean emit_signals;
111 GstAppSinkCallbacks callbacks;
113 GDestroyNotify notify;
115 gboolean buffer_lists_supported;
118 GST_DEBUG_CATEGORY_STATIC (app_sink_debug);
119 #define GST_CAT_DEFAULT app_sink_debug
127 SIGNAL_NEW_BUFFER_LIST,
132 SIGNAL_PULL_BUFFER_LIST,
137 #define DEFAULT_PROP_EOS TRUE
138 #define DEFAULT_PROP_EMIT_SIGNALS FALSE
139 #define DEFAULT_PROP_MAX_BUFFERS 0
140 #define DEFAULT_PROP_DROP FALSE
153 static GstStaticPadTemplate gst_app_sink_template =
154 GST_STATIC_PAD_TEMPLATE ("sink",
157 GST_STATIC_CAPS_ANY);
159 static void gst_app_sink_uri_handler_init (gpointer g_iface,
160 gpointer iface_data);
162 static void gst_app_sink_dispose (GObject * object);
163 static void gst_app_sink_finalize (GObject * object);
165 static void gst_app_sink_set_property (GObject * object, guint prop_id,
166 const GValue * value, GParamSpec * pspec);
167 static void gst_app_sink_get_property (GObject * object, guint prop_id,
168 GValue * value, GParamSpec * pspec);
170 static gboolean gst_app_sink_unlock_start (GstBaseSink * bsink);
171 static gboolean gst_app_sink_unlock_stop (GstBaseSink * bsink);
172 static gboolean gst_app_sink_start (GstBaseSink * psink);
173 static gboolean gst_app_sink_stop (GstBaseSink * psink);
174 static gboolean gst_app_sink_event (GstBaseSink * sink, GstEvent * event);
175 static GstFlowReturn gst_app_sink_preroll (GstBaseSink * psink,
177 static GstFlowReturn gst_app_sink_render_common (GstBaseSink * psink,
178 GstMiniObject * data, gboolean is_list);
179 static GstFlowReturn gst_app_sink_render (GstBaseSink * psink,
181 static GstFlowReturn gst_app_sink_render_list (GstBaseSink * psink,
182 GstBufferList * list);
183 static GstCaps *gst_app_sink_getcaps (GstBaseSink * psink);
184 static GstMiniObject *gst_app_sink_pull_object (GstAppSink * appsink);
186 static guint gst_app_sink_signals[LAST_SIGNAL] = { 0 };
189 _do_init (GType filesrc_type)
191 static const GInterfaceInfo urihandler_info = {
192 gst_app_sink_uri_handler_init,
196 g_type_add_interface_static (filesrc_type, GST_TYPE_URI_HANDLER,
200 GST_BOILERPLATE_FULL (GstAppSink, gst_app_sink, GstBaseSink, GST_TYPE_BASE_SINK,
203 /* Can't use glib-genmarshal for this, as it doesn't know how to handle
204 * GstMiniObject-based types, which are a new fundamental type */
206 gst_app_marshal_BUFFER__VOID (GClosure * closure,
207 GValue * return_value,
208 guint n_param_values,
209 const GValue * param_values,
210 gpointer invocation_hint, gpointer marshal_data)
212 typedef GstBuffer *(*GMarshalFunc_BUFFER__VOID) (gpointer data1,
214 register GMarshalFunc_BUFFER__VOID callback;
215 register GCClosure *cc = (GCClosure *) closure;
216 register gpointer data1, data2;
219 g_return_if_fail (return_value != NULL);
220 g_return_if_fail (n_param_values == 1);
222 if (G_CCLOSURE_SWAP_DATA (closure)) {
223 data1 = closure->data;
224 data2 = g_value_peek_pointer (param_values + 0);
226 data1 = g_value_peek_pointer (param_values + 0);
227 data2 = closure->data;
230 (GMarshalFunc_BUFFER__VOID) (marshal_data ? marshal_data : cc->callback);
232 v_return = callback (data1, data2);
234 gst_value_take_buffer (return_value, v_return);
238 gst_app_sink_base_init (gpointer g_class)
240 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
242 GST_DEBUG_CATEGORY_INIT (app_sink_debug, "appsink", 0, "appsink element");
244 gst_element_class_set_details_simple (element_class, "AppSink",
245 "Generic/Sink", "Allow the application to get access to raw buffer",
246 "David Schleef <ds@schleef.org>, Wim Taymans <wim.taymans@gmail.com>");
248 gst_element_class_add_pad_template (element_class,
249 gst_static_pad_template_get (&gst_app_sink_template));
253 gst_app_sink_class_init (GstAppSinkClass * klass)
255 GObjectClass *gobject_class = (GObjectClass *) klass;
256 GstBaseSinkClass *basesink_class = (GstBaseSinkClass *) klass;
258 gobject_class->dispose = gst_app_sink_dispose;
259 gobject_class->finalize = gst_app_sink_finalize;
261 gobject_class->set_property = gst_app_sink_set_property;
262 gobject_class->get_property = gst_app_sink_get_property;
264 g_object_class_install_property (gobject_class, PROP_CAPS,
265 g_param_spec_boxed ("caps", "Caps",
266 "The allowed caps for the sink pad", GST_TYPE_CAPS,
267 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
269 g_object_class_install_property (gobject_class, PROP_EOS,
270 g_param_spec_boolean ("eos", "EOS",
271 "Check if the sink is EOS or not started", DEFAULT_PROP_EOS,
272 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
274 g_object_class_install_property (gobject_class, PROP_EMIT_SIGNALS,
275 g_param_spec_boolean ("emit-signals", "Emit signals",
276 "Emit new-preroll, new-buffer and new-buffer-list signals",
277 DEFAULT_PROP_EMIT_SIGNALS,
278 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
280 g_object_class_install_property (gobject_class, PROP_MAX_BUFFERS,
281 g_param_spec_uint ("max-buffers", "Max Buffers",
282 "The maximum number of buffers to queue internally (0 = unlimited)",
283 0, G_MAXUINT, DEFAULT_PROP_MAX_BUFFERS,
284 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
286 g_object_class_install_property (gobject_class, PROP_DROP,
287 g_param_spec_boolean ("drop", "Drop",
288 "Drop old buffers when the buffer queue is filled", DEFAULT_PROP_DROP,
289 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
293 * @appsink: the appsink element that emited the signal
295 * Signal that the end-of-stream has been reached. This signal is emited from
296 * the steaming thread.
298 gst_app_sink_signals[SIGNAL_EOS] =
299 g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
300 G_STRUCT_OFFSET (GstAppSinkClass, eos),
301 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
303 * GstAppSink::new-preroll:
304 * @appsink: the appsink element that emited the signal
306 * Signal that a new preroll buffer is available.
308 * This signal is emited from the steaming thread and only when the
309 * "emit-signals" property is %TRUE.
311 * The new preroll buffer can be retrieved with the "pull-preroll" action
312 * signal or gst_app_sink_pull_preroll() either from this signal callback
313 * or from any other thread.
315 * Note that this signal is only emited when the "emit-signals" property is
316 * set to %TRUE, which it is not by default for performance reasons.
318 gst_app_sink_signals[SIGNAL_NEW_PREROLL] =
319 g_signal_new ("new-preroll", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
320 G_STRUCT_OFFSET (GstAppSinkClass, new_preroll),
321 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
323 * GstAppSink::new-buffer:
324 * @appsink: the appsink element that emited the signal
326 * Signal that a new buffer is available.
328 * This signal is emited from the steaming thread and only when the
329 * "emit-signals" property is %TRUE.
331 * The new buffer can be retrieved with the "pull-buffer" action
332 * signal or gst_app_sink_pull_buffer() either from this signal callback
333 * or from any other thread.
335 * Note that this signal is only emited when the "emit-signals" property is
336 * set to %TRUE, which it is not by default for performance reasons.
338 gst_app_sink_signals[SIGNAL_NEW_BUFFER] =
339 g_signal_new ("new-buffer", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
340 G_STRUCT_OFFSET (GstAppSinkClass, new_buffer),
341 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
343 * GstAppSink::new-buffer-list:
344 * @appsink: the appsink element that emited the signal
346 * Signal that a new bufferlist is available.
348 * This signal is emited from the steaming thread and only when the
349 * "emit-signals" property is %TRUE.
351 * The new buffer can be retrieved with the "pull-buffer-list" action
352 * signal or gst_app_sink_pull_buffer_list() either from this signal callback
353 * or from any other thread.
355 * Note that this signal is only emited when the "emit-signals" property is
356 * set to %TRUE, which it is not by default for performance reasons.
358 gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST] =
359 g_signal_new ("new-buffer-list", G_TYPE_FROM_CLASS (klass),
360 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstAppSinkClass, new_buffer_list),
361 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
364 * GstAppSink::pull-preroll:
365 * @appsink: the appsink element to emit this signal on
367 * Get the last preroll buffer in @appsink. This was the buffer that caused the
368 * appsink to preroll in the PAUSED state. This buffer can be pulled many times
369 * and remains available to the application even after EOS.
371 * This function is typically used when dealing with a pipeline in the PAUSED
372 * state. Calling this function after doing a seek will give the buffer right
373 * after the seek position.
375 * Note that the preroll buffer will also be returned as the first buffer
376 * when calling gst_app_sink_pull_buffer() or the "pull-buffer" action signal.
378 * If an EOS event was received before any buffers, this function returns
379 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
381 * This function blocks until a preroll buffer or EOS is received or the appsink
382 * element is set to the READY/NULL state.
384 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
386 gst_app_sink_signals[SIGNAL_PULL_PREROLL] =
387 g_signal_new ("pull-preroll", G_TYPE_FROM_CLASS (klass),
388 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
389 pull_preroll), NULL, NULL, gst_app_marshal_BUFFER__VOID,
390 GST_TYPE_BUFFER, 0, G_TYPE_NONE);
392 * GstAppSink::pull-buffer:
393 * @appsink: the appsink element to emit this signal on
395 * This function blocks until a buffer or EOS becomes available or the appsink
396 * element is set to the READY/NULL state.
398 * This function will only return buffers when the appsink is in the PLAYING
399 * state. All rendered buffers will be put in a queue so that the application
400 * can pull buffers at its own rate.
402 * Note that when the application does not pull buffers fast enough, the
403 * queued buffers could consume a lot of memory, especially when dealing with
404 * raw video frames. It's possible to control the behaviour of the queue with
405 * the "drop" and "max-buffers" properties.
407 * If an EOS event was received before any buffers, this function returns
408 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
410 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
412 gst_app_sink_signals[SIGNAL_PULL_BUFFER] =
413 g_signal_new ("pull-buffer", G_TYPE_FROM_CLASS (klass),
414 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
415 pull_buffer), NULL, NULL, gst_app_marshal_BUFFER__VOID,
416 GST_TYPE_BUFFER, 0, G_TYPE_NONE);
418 * GstAppSink::pull-buffer-list:
419 * @appsink: the appsink element to emit this signal on
421 * This function blocks until a buffer list or EOS becomes available or the appsink
422 * element is set to the READY/NULL state.
424 * This function will only return bufferlists when the appsink is in the PLAYING
425 * state. All rendered bufferlists will be put in a queue so that the application
426 * can pull bufferlists at its own rate.
428 * Note that when the application does not pull bufferlists fast enough, the
429 * queued bufferlists could consume a lot of memory, especially when dealing with
430 * raw video frames. It's possible to control the behaviour of the queue with
431 * the "drop" and "max-buffers" properties.
433 * If an EOS event was received before any buffers, this function returns
434 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
436 * Returns: a #GstBufferList or NULL when the appsink is stopped or EOS.
438 gst_app_sink_signals[SIGNAL_PULL_BUFFER_LIST] =
439 g_signal_new ("pull-buffer-list", G_TYPE_FROM_CLASS (klass),
440 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
441 pull_buffer_list), NULL, NULL, gst_app_marshal_BUFFER__VOID,
442 GST_TYPE_BUFFER_LIST, 0, G_TYPE_NONE);
444 basesink_class->unlock = gst_app_sink_unlock_start;
445 basesink_class->unlock_stop = gst_app_sink_unlock_stop;
446 basesink_class->start = gst_app_sink_start;
447 basesink_class->stop = gst_app_sink_stop;
448 basesink_class->event = gst_app_sink_event;
449 basesink_class->preroll = gst_app_sink_preroll;
450 basesink_class->render = gst_app_sink_render;
451 basesink_class->render_list = gst_app_sink_render_list;
452 basesink_class->get_caps = gst_app_sink_getcaps;
454 klass->pull_preroll = gst_app_sink_pull_preroll;
455 klass->pull_buffer = gst_app_sink_pull_buffer;
456 klass->pull_buffer_list = gst_app_sink_pull_buffer_list;
458 g_type_class_add_private (klass, sizeof (GstAppSinkPrivate));
462 gst_app_sink_init (GstAppSink * appsink, GstAppSinkClass * klass)
464 GstAppSinkPrivate *priv;
466 priv = appsink->priv =
467 G_TYPE_INSTANCE_GET_PRIVATE (appsink, GST_TYPE_APP_SINK,
470 priv->mutex = g_mutex_new ();
471 priv->cond = g_cond_new ();
472 priv->queue = g_queue_new ();
474 priv->emit_signals = DEFAULT_PROP_EMIT_SIGNALS;
475 priv->max_buffers = DEFAULT_PROP_MAX_BUFFERS;
476 priv->drop = DEFAULT_PROP_DROP;
480 gst_app_sink_dispose (GObject * obj)
482 GstAppSink *appsink = GST_APP_SINK_CAST (obj);
483 GstAppSinkPrivate *priv = appsink->priv;
484 GstMiniObject *queue_obj;
486 GST_OBJECT_LOCK (appsink);
488 gst_caps_unref (priv->caps);
492 priv->notify (priv->user_data);
494 priv->user_data = NULL;
497 GST_OBJECT_UNLOCK (appsink);
499 g_mutex_lock (priv->mutex);
501 gst_buffer_unref (priv->preroll);
502 priv->preroll = NULL;
504 while ((queue_obj = g_queue_pop_head (priv->queue)))
505 gst_mini_object_unref (queue_obj);
506 g_mutex_unlock (priv->mutex);
508 G_OBJECT_CLASS (parent_class)->dispose (obj);
512 gst_app_sink_finalize (GObject * obj)
514 GstAppSink *appsink = GST_APP_SINK_CAST (obj);
515 GstAppSinkPrivate *priv = appsink->priv;
517 g_mutex_free (priv->mutex);
518 g_cond_free (priv->cond);
519 g_queue_free (priv->queue);
521 G_OBJECT_CLASS (parent_class)->finalize (obj);
525 gst_app_sink_set_property (GObject * object, guint prop_id,
526 const GValue * value, GParamSpec * pspec)
528 GstAppSink *appsink = GST_APP_SINK_CAST (object);
532 gst_app_sink_set_caps (appsink, gst_value_get_caps (value));
534 case PROP_EMIT_SIGNALS:
535 gst_app_sink_set_emit_signals (appsink, g_value_get_boolean (value));
537 case PROP_MAX_BUFFERS:
538 gst_app_sink_set_max_buffers (appsink, g_value_get_uint (value));
541 gst_app_sink_set_drop (appsink, g_value_get_boolean (value));
544 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
550 gst_app_sink_get_property (GObject * object, guint prop_id, GValue * value,
553 GstAppSink *appsink = GST_APP_SINK_CAST (object);
560 caps = gst_app_sink_get_caps (appsink);
561 gst_value_set_caps (value, caps);
563 gst_caps_unref (caps);
567 g_value_set_boolean (value, gst_app_sink_is_eos (appsink));
569 case PROP_EMIT_SIGNALS:
570 g_value_set_boolean (value, gst_app_sink_get_emit_signals (appsink));
572 case PROP_MAX_BUFFERS:
573 g_value_set_uint (value, gst_app_sink_get_max_buffers (appsink));
576 g_value_set_boolean (value, gst_app_sink_get_drop (appsink));
579 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
585 gst_app_sink_unlock_start (GstBaseSink * bsink)
587 GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
588 GstAppSinkPrivate *priv = appsink->priv;
590 g_mutex_lock (priv->mutex);
591 GST_DEBUG_OBJECT (appsink, "unlock start");
593 g_cond_signal (priv->cond);
594 g_mutex_unlock (priv->mutex);
600 gst_app_sink_unlock_stop (GstBaseSink * bsink)
602 GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
603 GstAppSinkPrivate *priv = appsink->priv;
605 g_mutex_lock (priv->mutex);
606 GST_DEBUG_OBJECT (appsink, "unlock stop");
607 priv->unlock = FALSE;
608 g_cond_signal (priv->cond);
609 g_mutex_unlock (priv->mutex);
615 gst_app_sink_flush_unlocked (GstAppSink * appsink)
618 GstAppSinkPrivate *priv = appsink->priv;
620 GST_DEBUG_OBJECT (appsink, "flush stop appsink");
621 priv->is_eos = FALSE;
622 gst_buffer_replace (&priv->preroll, NULL);
623 while ((obj = g_queue_pop_head (priv->queue)))
624 gst_mini_object_unref (obj);
625 g_cond_signal (priv->cond);
628 #define NEW_BUFFER_LIST_SIGID \
629 gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST]
632 gst_app_sink_check_buffer_lists_support (GstAppSink * appsink)
636 ret = (appsink->priv->callbacks.new_buffer_list != NULL) ||
637 g_signal_has_handler_pending (appsink, NEW_BUFFER_LIST_SIGID, 0, FALSE);
639 GST_INFO_OBJECT (appsink, "application supports buffer lists: %d", ret);
644 gst_app_sink_start (GstBaseSink * psink)
646 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
647 GstAppSinkPrivate *priv = appsink->priv;
649 g_mutex_lock (priv->mutex);
650 GST_DEBUG_OBJECT (appsink, "starting");
651 priv->flushing = FALSE;
652 priv->started = TRUE;
653 priv->buffer_lists_supported =
654 gst_app_sink_check_buffer_lists_support (appsink);
655 g_mutex_unlock (priv->mutex);
661 gst_app_sink_stop (GstBaseSink * psink)
663 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
664 GstAppSinkPrivate *priv = appsink->priv;
666 g_mutex_lock (priv->mutex);
667 GST_DEBUG_OBJECT (appsink, "stopping");
668 priv->flushing = TRUE;
669 priv->started = FALSE;
670 gst_app_sink_flush_unlocked (appsink);
671 g_mutex_unlock (priv->mutex);
677 gst_app_sink_event (GstBaseSink * sink, GstEvent * event)
679 GstAppSink *appsink = GST_APP_SINK_CAST (sink);
680 GstAppSinkPrivate *priv = appsink->priv;
682 switch (event->type) {
685 g_mutex_lock (priv->mutex);
686 GST_DEBUG_OBJECT (appsink, "receiving EOS");
688 g_cond_signal (priv->cond);
689 g_mutex_unlock (priv->mutex);
692 if (priv->callbacks.eos)
693 priv->callbacks.eos (appsink, priv->user_data);
695 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_EOS], 0);
698 case GST_EVENT_FLUSH_START:
699 /* we don't have to do anything here, the base class will call unlock
700 * which will make sure we exit the _render method */
701 GST_DEBUG_OBJECT (appsink, "received FLUSH_START");
703 case GST_EVENT_FLUSH_STOP:
704 g_mutex_lock (priv->mutex);
705 GST_DEBUG_OBJECT (appsink, "received FLUSH_STOP");
706 gst_app_sink_flush_unlocked (appsink);
707 g_mutex_unlock (priv->mutex);
716 gst_app_sink_preroll (GstBaseSink * psink, GstBuffer * buffer)
718 GstFlowReturn res = GST_FLOW_OK;
719 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
720 GstAppSinkPrivate *priv = appsink->priv;
723 g_mutex_lock (priv->mutex);
727 GST_DEBUG_OBJECT (appsink, "setting preroll buffer %p", buffer);
728 gst_buffer_replace (&priv->preroll, buffer);
730 g_cond_signal (priv->cond);
731 emit = priv->emit_signals;
732 g_mutex_unlock (priv->mutex);
734 if (priv->callbacks.new_preroll)
735 res = priv->callbacks.new_preroll (appsink, priv->user_data);
737 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_PREROLL], 0);
743 GST_DEBUG_OBJECT (appsink, "we are flushing");
744 g_mutex_unlock (priv->mutex);
745 return GST_FLOW_WRONG_STATE;
750 gst_app_sink_render_common (GstBaseSink * psink, GstMiniObject * data,
754 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
755 GstAppSinkPrivate *priv = appsink->priv;
759 g_mutex_lock (priv->mutex);
763 GST_DEBUG_OBJECT (appsink, "pushing render buffer%s %p on queue (%d)",
764 is_list ? " list" : "", data, priv->queue->length);
766 while (priv->max_buffers > 0 && priv->queue->length >= priv->max_buffers) {
770 /* we need to drop the oldest buffer/list and try again */
771 obj = g_queue_pop_head (priv->queue);
772 GST_DEBUG_OBJECT (appsink, "dropping old buffer/list %p", obj);
773 gst_mini_object_unref (obj);
775 GST_DEBUG_OBJECT (appsink, "waiting for free space, length %d >= %d",
776 priv->queue->length, priv->max_buffers);
779 /* we are asked to unlock, call the wait_preroll method */
780 g_mutex_unlock (priv->mutex);
781 if ((ret = gst_base_sink_wait_preroll (psink)) != GST_FLOW_OK)
784 /* we are allowed to continue now */
788 /* wait for a buffer to be removed or flush */
789 g_cond_wait (priv->cond, priv->mutex);
794 /* we need to ref the buffer when pushing it in the queue */
795 g_queue_push_tail (priv->queue, gst_mini_object_ref (data));
796 g_cond_signal (priv->cond);
797 emit = priv->emit_signals;
798 g_mutex_unlock (priv->mutex);
801 if (priv->callbacks.new_buffer_list)
802 priv->callbacks.new_buffer_list (appsink, priv->user_data);
804 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST], 0);
806 if (priv->callbacks.new_buffer)
807 priv->callbacks.new_buffer (appsink, priv->user_data);
809 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER], 0);
815 GST_DEBUG_OBJECT (appsink, "we are flushing");
816 g_mutex_unlock (priv->mutex);
817 return GST_FLOW_WRONG_STATE;
821 GST_DEBUG_OBJECT (appsink, "we are stopping");
827 gst_app_sink_render (GstBaseSink * psink, GstBuffer * buffer)
829 return gst_app_sink_render_common (psink, GST_MINI_OBJECT_CAST (buffer),
834 gst_app_sink_render_list (GstBaseSink * sink, GstBufferList * list)
836 GstBufferListIterator *it;
841 appsink = GST_APP_SINK_CAST (sink);
843 if (appsink->priv->buffer_lists_supported)
844 return gst_app_sink_render_common (sink, GST_MINI_OBJECT_CAST (list), TRUE);
846 /* The application doesn't support buffer lists, extract individual buffers
847 * then and push them one-by-one */
848 GST_INFO_OBJECT (sink, "chaining each group in list as a merged buffer");
850 it = gst_buffer_list_iterate (list);
852 if (gst_buffer_list_iterator_next_group (it)) {
854 group = gst_buffer_list_iterator_merge_group (it);
856 group = gst_buffer_new ();
857 GST_DEBUG_OBJECT (sink, "chaining empty group");
859 GST_DEBUG_OBJECT (sink, "chaining group");
861 flow = gst_app_sink_render (sink, group);
862 gst_buffer_unref (group);
863 } while (flow == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
865 GST_DEBUG_OBJECT (sink, "chaining empty group");
866 group = gst_buffer_new ();
867 flow = gst_app_sink_render (sink, group);
868 gst_buffer_unref (group);
871 gst_buffer_list_iterator_free (it);
877 gst_app_sink_getcaps (GstBaseSink * psink)
880 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
881 GstAppSinkPrivate *priv = appsink->priv;
883 GST_OBJECT_LOCK (appsink);
884 if ((caps = priv->caps))
886 GST_DEBUG_OBJECT (appsink, "got caps %" GST_PTR_FORMAT, caps);
887 GST_OBJECT_UNLOCK (appsink);
892 static GstMiniObject *
893 gst_app_sink_pull_object (GstAppSink * appsink)
895 GstMiniObject *obj = NULL;
896 GstAppSinkPrivate *priv;
898 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
900 priv = appsink->priv;
902 g_mutex_lock (priv->mutex);
905 GST_DEBUG_OBJECT (appsink, "trying to grab a buffer/list");
909 if (!g_queue_is_empty (priv->queue))
915 /* nothing to return, wait */
916 GST_DEBUG_OBJECT (appsink, "waiting for a buffer/list");
917 g_cond_wait (priv->cond, priv->mutex);
919 obj = g_queue_pop_head (priv->queue);
920 GST_DEBUG_OBJECT (appsink, "we have a buffer/list %p", obj);
921 g_cond_signal (priv->cond);
922 g_mutex_unlock (priv->mutex);
926 /* special conditions */
929 GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
930 g_mutex_unlock (priv->mutex);
935 GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
936 g_mutex_unlock (priv->mutex);
944 * gst_app_sink_set_caps:
945 * @appsink: a #GstAppSink
948 * Set the capabilities on the appsink element. This function takes
949 * a copy of the caps structure. After calling this method, the sink will only
950 * accept caps that match @caps. If @caps is non-fixed, you must check the caps
951 * on the buffers to get the actual used caps.
956 gst_app_sink_set_caps (GstAppSink * appsink, const GstCaps * caps)
959 GstAppSinkPrivate *priv;
961 g_return_if_fail (GST_IS_APP_SINK (appsink));
963 priv = appsink->priv;
965 GST_OBJECT_LOCK (appsink);
966 GST_DEBUG_OBJECT (appsink, "setting caps to %" GST_PTR_FORMAT, caps);
967 if ((old = priv->caps) != caps) {
969 priv->caps = gst_caps_copy (caps);
973 gst_caps_unref (old);
975 GST_OBJECT_UNLOCK (appsink);
979 * gst_app_sink_get_caps:
980 * @appsink: a #GstAppSink
982 * Get the configured caps on @appsink.
984 * Returns: the #GstCaps accepted by the sink. gst_caps_unref() after usage.
989 gst_app_sink_get_caps (GstAppSink * appsink)
992 GstAppSinkPrivate *priv;
994 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
996 priv = appsink->priv;
998 GST_OBJECT_LOCK (appsink);
999 if ((caps = priv->caps))
1000 gst_caps_ref (caps);
1001 GST_DEBUG_OBJECT (appsink, "getting caps of %" GST_PTR_FORMAT, caps);
1002 GST_OBJECT_UNLOCK (appsink);
1008 * gst_app_sink_is_eos:
1009 * @appsink: a #GstAppSink
1011 * Check if @appsink is EOS, which is when no more buffers can be pulled because
1012 * an EOS event was received.
1014 * This function also returns %TRUE when the appsink is not in the PAUSED or
1017 * Returns: %TRUE if no more buffers can be pulled and the appsink is EOS.
1022 gst_app_sink_is_eos (GstAppSink * appsink)
1025 GstAppSinkPrivate *priv;
1027 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1029 priv = appsink->priv;
1031 g_mutex_lock (priv->mutex);
1035 if (priv->is_eos && g_queue_is_empty (priv->queue)) {
1036 GST_DEBUG_OBJECT (appsink, "we are EOS and the queue is empty");
1039 GST_DEBUG_OBJECT (appsink, "we are not yet EOS");
1042 g_mutex_unlock (priv->mutex);
1048 GST_DEBUG_OBJECT (appsink, "we are stopped, return TRUE");
1049 g_mutex_unlock (priv->mutex);
1055 * gst_app_sink_set_emit_signals:
1056 * @appsink: a #GstAppSink
1057 * @emit: the new state
1059 * Make appsink emit the "new-preroll" and "new-buffer" signals. This option is
1060 * by default disabled because signal emission is expensive and unneeded when
1061 * the application prefers to operate in pull mode.
1066 gst_app_sink_set_emit_signals (GstAppSink * appsink, gboolean emit)
1068 GstAppSinkPrivate *priv;
1070 g_return_if_fail (GST_IS_APP_SINK (appsink));
1072 priv = appsink->priv;
1074 g_mutex_lock (priv->mutex);
1075 priv->emit_signals = emit;
1076 g_mutex_unlock (priv->mutex);
1080 * gst_app_sink_get_emit_signals:
1081 * @appsink: a #GstAppSink
1083 * Check if appsink will emit the "new-preroll" and "new-buffer" signals.
1085 * Returns: %TRUE if @appsink is emiting the "new-preroll" and "new-buffer"
1091 gst_app_sink_get_emit_signals (GstAppSink * appsink)
1094 GstAppSinkPrivate *priv;
1096 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1098 priv = appsink->priv;
1100 g_mutex_lock (priv->mutex);
1101 result = priv->emit_signals;
1102 g_mutex_unlock (priv->mutex);
1108 * gst_app_sink_set_max_buffers:
1109 * @appsink: a #GstAppSink
1110 * @max: the maximum number of buffers to queue
1112 * Set the maximum amount of buffers that can be queued in @appsink. After this
1113 * amount of buffers are queued in appsink, any more buffers will block upstream
1114 * elements until a buffer is pulled from @appsink.
1119 gst_app_sink_set_max_buffers (GstAppSink * appsink, guint max)
1121 GstAppSinkPrivate *priv;
1123 g_return_if_fail (GST_IS_APP_SINK (appsink));
1125 priv = appsink->priv;
1127 g_mutex_lock (priv->mutex);
1128 if (max != priv->max_buffers) {
1129 priv->max_buffers = max;
1130 /* signal the change */
1131 g_cond_signal (priv->cond);
1133 g_mutex_unlock (priv->mutex);
1137 * gst_app_sink_get_max_buffers:
1138 * @appsink: a #GstAppSink
1140 * Get the maximum amount of buffers that can be queued in @appsink.
1142 * Returns: The maximum amount of buffers that can be queued.
1147 gst_app_sink_get_max_buffers (GstAppSink * appsink)
1150 GstAppSinkPrivate *priv;
1152 g_return_val_if_fail (GST_IS_APP_SINK (appsink), 0);
1154 priv = appsink->priv;
1156 g_mutex_lock (priv->mutex);
1157 result = priv->max_buffers;
1158 g_mutex_unlock (priv->mutex);
1164 * gst_app_sink_set_drop:
1165 * @appsink: a #GstAppSink
1166 * @drop: the new state
1168 * Instruct @appsink to drop old buffers when the maximum amount of queued
1169 * buffers is reached.
1174 gst_app_sink_set_drop (GstAppSink * appsink, gboolean drop)
1176 GstAppSinkPrivate *priv;
1178 g_return_if_fail (GST_IS_APP_SINK (appsink));
1180 priv = appsink->priv;
1182 g_mutex_lock (priv->mutex);
1183 if (priv->drop != drop) {
1185 /* signal the change */
1186 g_cond_signal (priv->cond);
1188 g_mutex_unlock (priv->mutex);
1192 * gst_app_sink_get_drop:
1193 * @appsink: a #GstAppSink
1195 * Check if @appsink will drop old buffers when the maximum amount of queued
1196 * buffers is reached.
1198 * Returns: %TRUE if @appsink is dropping old buffers when the queue is
1204 gst_app_sink_get_drop (GstAppSink * appsink)
1207 GstAppSinkPrivate *priv;
1209 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1211 priv = appsink->priv;
1213 g_mutex_lock (priv->mutex);
1214 result = priv->drop;
1215 g_mutex_unlock (priv->mutex);
1221 * gst_app_sink_pull_preroll:
1222 * @appsink: a #GstAppSink
1224 * Get the last preroll buffer in @appsink. This was the buffer that caused the
1225 * appsink to preroll in the PAUSED state. This buffer can be pulled many times
1226 * and remains available to the application even after EOS.
1228 * This function is typically used when dealing with a pipeline in the PAUSED
1229 * state. Calling this function after doing a seek will give the buffer right
1230 * after the seek position.
1232 * Note that the preroll buffer will also be returned as the first buffer
1233 * when calling gst_app_sink_pull_buffer().
1235 * If an EOS event was received before any buffers, this function returns
1236 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1238 * This function blocks until a preroll buffer or EOS is received or the appsink
1239 * element is set to the READY/NULL state.
1241 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
1246 gst_app_sink_pull_preroll (GstAppSink * appsink)
1248 GstBuffer *buf = NULL;
1249 GstAppSinkPrivate *priv;
1251 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
1253 priv = appsink->priv;
1255 g_mutex_lock (priv->mutex);
1258 GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
1262 if (priv->preroll != NULL)
1268 /* nothing to return, wait */
1269 GST_DEBUG_OBJECT (appsink, "waiting for the preroll buffer");
1270 g_cond_wait (priv->cond, priv->mutex);
1272 buf = gst_buffer_ref (priv->preroll);
1273 GST_DEBUG_OBJECT (appsink, "we have the preroll buffer %p", buf);
1274 g_mutex_unlock (priv->mutex);
1278 /* special conditions */
1281 GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
1282 g_mutex_unlock (priv->mutex);
1287 GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
1288 g_mutex_unlock (priv->mutex);
1294 * gst_app_sink_pull_buffer:
1295 * @appsink: a #GstAppSink
1297 * This function blocks until a buffer or EOS becomes available or the appsink
1298 * element is set to the READY/NULL state.
1300 * This function will only return buffers when the appsink is in the PLAYING
1301 * state. All rendered buffers will be put in a queue so that the application
1302 * can pull buffers at its own rate. Note that when the application does not
1303 * pull buffers fast enough, the queued buffers could consume a lot of memory,
1304 * especially when dealing with raw video frames.
1306 * If an EOS event was received before any buffers, this function returns
1307 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1309 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
1315 gst_app_sink_pull_buffer (GstAppSink * appsink)
1317 GST_DEBUG_OBJECT (appsink, "pull a buffer");
1318 return GST_BUFFER_CAST (gst_app_sink_pull_object (appsink));
1322 * gst_app_sink_pull_buffer_list:
1323 * @appsink: a #GstAppSink
1325 * This function blocks until a buffer list or EOS becomes available or the
1326 * appsink element is set to the READY/NULL state.
1328 * This function will only return buffer lists when the appsink is in the
1329 * PLAYING state. All rendered buffer lists will be put in a queue so that
1330 * the application can pull buffer lists at its own rate. Note that when
1331 * the application does not pull buffer lists fast enough, the queued buffer
1332 * lists could consume a lot of memory, especially when dealing with raw
1335 * If an EOS event was received before any buffer lists, this function returns
1336 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1338 * Returns: a #GstBufferList or NULL when the appsink is stopped or EOS.
1341 gst_app_sink_pull_buffer_list (GstAppSink * appsink)
1343 GST_DEBUG_OBJECT (appsink, "pull a buffer list");
1344 return GST_BUFFER_LIST_CAST (gst_app_sink_pull_object (appsink));
1348 * gst_app_sink_set_callbacks:
1349 * @appsink: a #GstAppSink
1350 * @callbacks: the callbacks
1351 * @user_data: a user_data argument for the callbacks
1352 * @notify: a destroy notify function
1354 * Set callbacks which will be executed for each new preroll, new buffer and eos.
1355 * This is an alternative to using the signals, it has lower overhead and is thus
1356 * less expensive, but also less flexible.
1358 * If callbacks are installed, no signals will be emited for performance
1364 gst_app_sink_set_callbacks (GstAppSink * appsink,
1365 GstAppSinkCallbacks * callbacks, gpointer user_data, GDestroyNotify notify)
1367 GDestroyNotify old_notify;
1368 GstAppSinkPrivate *priv;
1370 g_return_if_fail (GST_IS_APP_SINK (appsink));
1371 g_return_if_fail (callbacks != NULL);
1373 priv = appsink->priv;
1375 GST_OBJECT_LOCK (appsink);
1376 old_notify = priv->notify;
1381 old_data = priv->user_data;
1383 priv->user_data = NULL;
1384 priv->notify = NULL;
1385 GST_OBJECT_UNLOCK (appsink);
1387 old_notify (old_data);
1389 GST_OBJECT_LOCK (appsink);
1391 priv->callbacks = *callbacks;
1392 priv->user_data = user_data;
1393 priv->notify = notify;
1394 priv->buffer_lists_supported =
1395 gst_app_sink_check_buffer_lists_support (appsink);
1396 GST_OBJECT_UNLOCK (appsink);
1399 /*** GSTURIHANDLER INTERFACE *************************************************/
1402 gst_app_sink_uri_get_type (void)
1404 return GST_URI_SINK;
1408 gst_app_sink_uri_get_protocols (void)
1410 static gchar *protocols[] = { (char *) "appsink", NULL };
1415 static const gchar *
1416 gst_app_sink_uri_get_uri (GstURIHandler * handler)
1422 gst_app_sink_uri_set_uri (GstURIHandler * handler, const gchar * uri)
1427 protocol = gst_uri_get_protocol (uri);
1428 ret = !strcmp (protocol, "appsink");
1435 gst_app_sink_uri_handler_init (gpointer g_iface, gpointer iface_data)
1437 GstURIHandlerInterface *iface = (GstURIHandlerInterface *) g_iface;
1439 iface->get_type = gst_app_sink_uri_get_type;
1440 iface->get_protocols = gst_app_sink_uri_get_protocols;
1441 iface->get_uri = gst_app_sink_uri_get_uri;
1442 iface->set_uri = gst_app_sink_uri_set_uri;