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 * @short_description: Easy way for applications to extract buffers from a
24 * @see_also: #GstBaseSink, appsrc
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.
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.
33 * The normal way of retrieving buffers from appsink is by using the
34 * gst_app_sink_pull_buffer() and gst_app_sink_pull_preroll() methods.
35 * These methods block until a buffer becomes available in the sink or when the
36 * sink is shut down or reaches EOS.
38 * Appsink will internally use a queue to collect buffers from the streaming
39 * thread. If the application is not pulling buffers fast enough, this queue
40 * will consume a lot of memory over time. The "max-buffers" property can be
41 * used to limit the queue size. The "drop" property controls whether the
42 * streaming thread blocks or if older buffers are dropped when the maximum
43 * queue size is reached. Note that blocking the streaming thread can negatively
44 * affect real-time performance and should be avoided.
46 * If a blocking behaviour is not desirable, setting the "emit-signals" property
47 * to %TRUE will make appsink emit the "new-buffer" and "new-preroll" signals
48 * when a buffer can be pulled without blocking.
50 * The "caps" property on appsink can be used to control the formats that
51 * appsink can receive. This property can contain non-fixed caps, the format of
52 * the pulled buffers can be obtained by getting the buffer caps.
54 * If one of the pull-preroll or pull-buffer methods return %NULL, the appsink
55 * is stopped or in the EOS state. You can check for the EOS state with the
56 * "eos" property or with the gst_app_sink_is_eos() method.
58 * The eos signal can also be used to be informed when the EOS state is reached
61 * Last reviewed on 2008-12-17 (0.10.22)
71 #include <gst/base/gstbasesink.h>
72 #include <gst/gstbuffer.h>
73 #include <gst/gstbufferlist.h>
77 #include "gstappsink.h"
79 #include "gst/glib-compat-private.h"
81 struct _GstAppSinkPrivate
84 gboolean emit_signals;
97 GstAppSinkCallbacks callbacks;
99 GDestroyNotify notify;
101 gboolean buffer_lists_supported;
104 GST_DEBUG_CATEGORY_STATIC (app_sink_debug);
105 #define GST_CAT_DEFAULT app_sink_debug
113 SIGNAL_NEW_BUFFER_LIST,
118 SIGNAL_PULL_BUFFER_LIST,
123 #define DEFAULT_PROP_EOS TRUE
124 #define DEFAULT_PROP_EMIT_SIGNALS FALSE
125 #define DEFAULT_PROP_MAX_BUFFERS 0
126 #define DEFAULT_PROP_DROP FALSE
139 static GstStaticPadTemplate gst_app_sink_template =
140 GST_STATIC_PAD_TEMPLATE ("sink",
143 GST_STATIC_CAPS_ANY);
145 static void gst_app_sink_uri_handler_init (gpointer g_iface,
146 gpointer iface_data);
148 static void gst_app_sink_dispose (GObject * object);
149 static void gst_app_sink_finalize (GObject * object);
151 static void gst_app_sink_set_property (GObject * object, guint prop_id,
152 const GValue * value, GParamSpec * pspec);
153 static void gst_app_sink_get_property (GObject * object, guint prop_id,
154 GValue * value, GParamSpec * pspec);
156 static gboolean gst_app_sink_unlock_start (GstBaseSink * bsink);
157 static gboolean gst_app_sink_unlock_stop (GstBaseSink * bsink);
158 static gboolean gst_app_sink_start (GstBaseSink * psink);
159 static gboolean gst_app_sink_stop (GstBaseSink * psink);
160 static gboolean gst_app_sink_event (GstBaseSink * sink, GstEvent * event);
161 static GstFlowReturn gst_app_sink_preroll (GstBaseSink * psink,
163 static GstFlowReturn gst_app_sink_render_common (GstBaseSink * psink,
164 GstMiniObject * data, gboolean is_list);
165 static GstFlowReturn gst_app_sink_render (GstBaseSink * psink,
167 static GstFlowReturn gst_app_sink_render_list (GstBaseSink * psink,
168 GstBufferList * list);
169 static GstCaps *gst_app_sink_getcaps (GstBaseSink * psink);
170 static GstMiniObject *gst_app_sink_pull_object (GstAppSink * appsink);
172 static guint gst_app_sink_signals[LAST_SIGNAL] = { 0 };
175 _do_init (GType filesrc_type)
177 static const GInterfaceInfo urihandler_info = {
178 gst_app_sink_uri_handler_init,
182 g_type_add_interface_static (filesrc_type, GST_TYPE_URI_HANDLER,
186 GST_BOILERPLATE_FULL (GstAppSink, gst_app_sink, GstBaseSink, GST_TYPE_BASE_SINK,
189 /* Can't use glib-genmarshal for this, as it doesn't know how to handle
190 * GstMiniObject-based types, which are a new fundamental type */
192 gst_app_marshal_BUFFER__VOID (GClosure * closure,
193 GValue * return_value,
194 guint n_param_values,
195 const GValue * param_values,
196 gpointer invocation_hint, gpointer marshal_data)
198 typedef GstBuffer *(*GMarshalFunc_BUFFER__VOID) (gpointer data1,
200 register GMarshalFunc_BUFFER__VOID callback;
201 register GCClosure *cc = (GCClosure *) closure;
202 register gpointer data1, data2;
205 g_return_if_fail (return_value != NULL);
206 g_return_if_fail (n_param_values == 1);
208 if (G_CCLOSURE_SWAP_DATA (closure)) {
209 data1 = closure->data;
210 data2 = g_value_peek_pointer (param_values + 0);
212 data1 = g_value_peek_pointer (param_values + 0);
213 data2 = closure->data;
216 (GMarshalFunc_BUFFER__VOID) (marshal_data ? marshal_data : cc->callback);
218 v_return = callback (data1, data2);
220 gst_value_take_buffer (return_value, v_return);
224 gst_app_sink_base_init (gpointer g_class)
226 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
228 GST_DEBUG_CATEGORY_INIT (app_sink_debug, "appsink", 0, "appsink element");
230 gst_element_class_set_details_simple (element_class, "AppSink",
231 "Generic/Sink", "Allow the application to get access to raw buffer",
232 "David Schleef <ds@schleef.org>, Wim Taymans <wim.taymans@gmail.com>");
234 gst_element_class_add_static_pad_template (element_class,
235 &gst_app_sink_template);
239 gst_app_sink_class_init (GstAppSinkClass * klass)
241 GObjectClass *gobject_class = (GObjectClass *) klass;
242 GstBaseSinkClass *basesink_class = (GstBaseSinkClass *) klass;
244 gobject_class->dispose = gst_app_sink_dispose;
245 gobject_class->finalize = gst_app_sink_finalize;
247 gobject_class->set_property = gst_app_sink_set_property;
248 gobject_class->get_property = gst_app_sink_get_property;
250 g_object_class_install_property (gobject_class, PROP_CAPS,
251 g_param_spec_boxed ("caps", "Caps",
252 "The allowed caps for the sink pad", GST_TYPE_CAPS,
253 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
255 g_object_class_install_property (gobject_class, PROP_EOS,
256 g_param_spec_boolean ("eos", "EOS",
257 "Check if the sink is EOS or not started", DEFAULT_PROP_EOS,
258 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
260 g_object_class_install_property (gobject_class, PROP_EMIT_SIGNALS,
261 g_param_spec_boolean ("emit-signals", "Emit signals",
262 "Emit new-preroll, new-buffer and new-buffer-list signals",
263 DEFAULT_PROP_EMIT_SIGNALS,
264 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
266 g_object_class_install_property (gobject_class, PROP_MAX_BUFFERS,
267 g_param_spec_uint ("max-buffers", "Max Buffers",
268 "The maximum number of buffers to queue internally (0 = unlimited)",
269 0, G_MAXUINT, DEFAULT_PROP_MAX_BUFFERS,
270 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
272 g_object_class_install_property (gobject_class, PROP_DROP,
273 g_param_spec_boolean ("drop", "Drop",
274 "Drop old buffers when the buffer queue is filled", DEFAULT_PROP_DROP,
275 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
279 * @appsink: the appsink element that emitted the signal
281 * Signal that the end-of-stream has been reached. This signal is emitted from
282 * the steaming thread.
284 gst_app_sink_signals[SIGNAL_EOS] =
285 g_signal_new ("eos", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
286 G_STRUCT_OFFSET (GstAppSinkClass, eos),
287 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
289 * GstAppSink::new-preroll:
290 * @appsink: the appsink element that emitted the signal
292 * Signal that a new preroll buffer is available.
294 * This signal is emitted from the steaming thread and only when the
295 * "emit-signals" property is %TRUE.
297 * The new preroll buffer can be retrieved with the "pull-preroll" action
298 * signal or gst_app_sink_pull_preroll() either from this signal callback
299 * or from any other thread.
301 * Note that this signal is only emitted when the "emit-signals" property is
302 * set to %TRUE, which it is not by default for performance reasons.
304 gst_app_sink_signals[SIGNAL_NEW_PREROLL] =
305 g_signal_new ("new-preroll", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
306 G_STRUCT_OFFSET (GstAppSinkClass, new_preroll),
307 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
309 * GstAppSink::new-buffer:
310 * @appsink: the appsink element that emitted the signal
312 * Signal that a new buffer is available.
314 * This signal is emitted from the steaming thread and only when the
315 * "emit-signals" property is %TRUE.
317 * The new buffer can be retrieved with the "pull-buffer" action
318 * signal or gst_app_sink_pull_buffer() either from this signal callback
319 * or from any other thread.
321 * Note that this signal is only emitted when the "emit-signals" property is
322 * set to %TRUE, which it is not by default for performance reasons.
324 gst_app_sink_signals[SIGNAL_NEW_BUFFER] =
325 g_signal_new ("new-buffer", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
326 G_STRUCT_OFFSET (GstAppSinkClass, new_buffer),
327 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
329 * GstAppSink::new-buffer-list:
330 * @appsink: the appsink element that emitted the signal
332 * Signal that a new bufferlist is available.
334 * This signal is emitted from the steaming thread and only when the
335 * "emit-signals" property is %TRUE.
337 * The new buffer can be retrieved with the "pull-buffer-list" action
338 * signal or gst_app_sink_pull_buffer_list() either from this signal callback
339 * or from any other thread.
341 * Note that this signal is only emitted when the "emit-signals" property is
342 * set to %TRUE, which it is not by default for performance reasons.
344 gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST] =
345 g_signal_new ("new-buffer-list", G_TYPE_FROM_CLASS (klass),
346 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstAppSinkClass, new_buffer_list),
347 NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0, G_TYPE_NONE);
350 * GstAppSink::pull-preroll:
351 * @appsink: the appsink element to emit this signal on
353 * Get the last preroll buffer in @appsink. This was the buffer that caused the
354 * appsink to preroll in the PAUSED state. This buffer can be pulled many times
355 * and remains available to the application even after EOS.
357 * This function is typically used when dealing with a pipeline in the PAUSED
358 * state. Calling this function after doing a seek will give the buffer right
359 * after the seek position.
361 * Note that the preroll buffer will also be returned as the first buffer
362 * when calling gst_app_sink_pull_buffer() or the "pull-buffer" action signal.
364 * If an EOS event was received before any buffers, this function returns
365 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
367 * This function blocks until a preroll buffer or EOS is received or the appsink
368 * element is set to the READY/NULL state.
370 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
372 gst_app_sink_signals[SIGNAL_PULL_PREROLL] =
373 g_signal_new ("pull-preroll", G_TYPE_FROM_CLASS (klass),
374 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
375 pull_preroll), NULL, NULL, gst_app_marshal_BUFFER__VOID,
376 GST_TYPE_BUFFER, 0, G_TYPE_NONE);
378 * GstAppSink::pull-buffer:
379 * @appsink: the appsink element to emit this signal on
381 * This function blocks until a buffer or EOS becomes available or the appsink
382 * element is set to the READY/NULL state.
384 * This function will only return buffers when the appsink is in the PLAYING
385 * state. All rendered buffers will be put in a queue so that the application
386 * can pull buffers at its own rate.
388 * Note that when the application does not pull buffers fast enough, the
389 * queued buffers could consume a lot of memory, especially when dealing with
390 * raw video frames. It's possible to control the behaviour of the queue with
391 * the "drop" and "max-buffers" properties.
393 * If an EOS event was received before any buffers, this function returns
394 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
396 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
398 gst_app_sink_signals[SIGNAL_PULL_BUFFER] =
399 g_signal_new ("pull-buffer", G_TYPE_FROM_CLASS (klass),
400 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
401 pull_buffer), NULL, NULL, gst_app_marshal_BUFFER__VOID,
402 GST_TYPE_BUFFER, 0, G_TYPE_NONE);
404 * GstAppSink::pull-buffer-list:
405 * @appsink: the appsink element to emit this signal on
407 * This function blocks until a buffer list or EOS becomes available or the appsink
408 * element is set to the READY/NULL state.
410 * This function will only return bufferlists when the appsink is in the PLAYING
411 * state. All rendered bufferlists will be put in a queue so that the application
412 * can pull bufferlists at its own rate.
414 * Note that when the application does not pull bufferlists fast enough, the
415 * queued bufferlists could consume a lot of memory, especially when dealing with
416 * raw video frames. It's possible to control the behaviour of the queue with
417 * the "drop" and "max-buffers" properties.
419 * If an EOS event was received before any buffers, this function returns
420 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
422 * Returns: a #GstBufferList or NULL when the appsink is stopped or EOS.
424 gst_app_sink_signals[SIGNAL_PULL_BUFFER_LIST] =
425 g_signal_new ("pull-buffer-list", G_TYPE_FROM_CLASS (klass),
426 G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, G_STRUCT_OFFSET (GstAppSinkClass,
427 pull_buffer_list), NULL, NULL, gst_app_marshal_BUFFER__VOID,
428 GST_TYPE_BUFFER_LIST, 0, G_TYPE_NONE);
430 basesink_class->unlock = gst_app_sink_unlock_start;
431 basesink_class->unlock_stop = gst_app_sink_unlock_stop;
432 basesink_class->start = gst_app_sink_start;
433 basesink_class->stop = gst_app_sink_stop;
434 basesink_class->event = gst_app_sink_event;
435 basesink_class->preroll = gst_app_sink_preroll;
436 basesink_class->render = gst_app_sink_render;
437 basesink_class->render_list = gst_app_sink_render_list;
438 basesink_class->get_caps = gst_app_sink_getcaps;
440 klass->pull_preroll = gst_app_sink_pull_preroll;
441 klass->pull_buffer = gst_app_sink_pull_buffer;
442 klass->pull_buffer_list = gst_app_sink_pull_buffer_list;
444 g_type_class_add_private (klass, sizeof (GstAppSinkPrivate));
448 gst_app_sink_init (GstAppSink * appsink, GstAppSinkClass * klass)
450 GstAppSinkPrivate *priv;
452 priv = appsink->priv =
453 G_TYPE_INSTANCE_GET_PRIVATE (appsink, GST_TYPE_APP_SINK,
456 priv->mutex = g_mutex_new ();
457 priv->cond = g_cond_new ();
458 priv->queue = g_queue_new ();
460 priv->emit_signals = DEFAULT_PROP_EMIT_SIGNALS;
461 priv->max_buffers = DEFAULT_PROP_MAX_BUFFERS;
462 priv->drop = DEFAULT_PROP_DROP;
466 gst_app_sink_dispose (GObject * obj)
468 GstAppSink *appsink = GST_APP_SINK_CAST (obj);
469 GstAppSinkPrivate *priv = appsink->priv;
470 GstMiniObject *queue_obj;
472 GST_OBJECT_LOCK (appsink);
474 gst_caps_unref (priv->caps);
478 priv->notify (priv->user_data);
480 priv->user_data = NULL;
483 GST_OBJECT_UNLOCK (appsink);
485 g_mutex_lock (priv->mutex);
487 gst_buffer_unref (priv->preroll);
488 priv->preroll = NULL;
490 while ((queue_obj = g_queue_pop_head (priv->queue)))
491 gst_mini_object_unref (queue_obj);
492 g_mutex_unlock (priv->mutex);
494 G_OBJECT_CLASS (parent_class)->dispose (obj);
498 gst_app_sink_finalize (GObject * obj)
500 GstAppSink *appsink = GST_APP_SINK_CAST (obj);
501 GstAppSinkPrivate *priv = appsink->priv;
503 g_mutex_free (priv->mutex);
504 g_cond_free (priv->cond);
505 g_queue_free (priv->queue);
507 G_OBJECT_CLASS (parent_class)->finalize (obj);
511 gst_app_sink_set_property (GObject * object, guint prop_id,
512 const GValue * value, GParamSpec * pspec)
514 GstAppSink *appsink = GST_APP_SINK_CAST (object);
518 gst_app_sink_set_caps (appsink, gst_value_get_caps (value));
520 case PROP_EMIT_SIGNALS:
521 gst_app_sink_set_emit_signals (appsink, g_value_get_boolean (value));
523 case PROP_MAX_BUFFERS:
524 gst_app_sink_set_max_buffers (appsink, g_value_get_uint (value));
527 gst_app_sink_set_drop (appsink, g_value_get_boolean (value));
530 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
536 gst_app_sink_get_property (GObject * object, guint prop_id, GValue * value,
539 GstAppSink *appsink = GST_APP_SINK_CAST (object);
546 caps = gst_app_sink_get_caps (appsink);
547 gst_value_set_caps (value, caps);
549 gst_caps_unref (caps);
553 g_value_set_boolean (value, gst_app_sink_is_eos (appsink));
555 case PROP_EMIT_SIGNALS:
556 g_value_set_boolean (value, gst_app_sink_get_emit_signals (appsink));
558 case PROP_MAX_BUFFERS:
559 g_value_set_uint (value, gst_app_sink_get_max_buffers (appsink));
562 g_value_set_boolean (value, gst_app_sink_get_drop (appsink));
565 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
571 gst_app_sink_unlock_start (GstBaseSink * bsink)
573 GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
574 GstAppSinkPrivate *priv = appsink->priv;
576 g_mutex_lock (priv->mutex);
577 GST_DEBUG_OBJECT (appsink, "unlock start");
579 g_cond_signal (priv->cond);
580 g_mutex_unlock (priv->mutex);
586 gst_app_sink_unlock_stop (GstBaseSink * bsink)
588 GstAppSink *appsink = GST_APP_SINK_CAST (bsink);
589 GstAppSinkPrivate *priv = appsink->priv;
591 g_mutex_lock (priv->mutex);
592 GST_DEBUG_OBJECT (appsink, "unlock stop");
593 priv->unlock = FALSE;
594 g_cond_signal (priv->cond);
595 g_mutex_unlock (priv->mutex);
601 gst_app_sink_flush_unlocked (GstAppSink * appsink)
604 GstAppSinkPrivate *priv = appsink->priv;
606 GST_DEBUG_OBJECT (appsink, "flush stop appsink");
607 priv->is_eos = FALSE;
608 gst_buffer_replace (&priv->preroll, NULL);
609 while ((obj = g_queue_pop_head (priv->queue)))
610 gst_mini_object_unref (obj);
611 g_cond_signal (priv->cond);
614 #define NEW_BUFFER_LIST_SIGID \
615 gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST]
618 gst_app_sink_check_buffer_lists_support (GstAppSink * appsink)
622 ret = (appsink->priv->callbacks.new_buffer_list != NULL) ||
623 g_signal_has_handler_pending (appsink, NEW_BUFFER_LIST_SIGID, 0, FALSE);
625 GST_INFO_OBJECT (appsink, "application supports buffer lists: %d", ret);
630 gst_app_sink_start (GstBaseSink * psink)
632 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
633 GstAppSinkPrivate *priv = appsink->priv;
635 g_mutex_lock (priv->mutex);
636 GST_DEBUG_OBJECT (appsink, "starting");
637 priv->flushing = FALSE;
638 priv->started = TRUE;
639 priv->buffer_lists_supported =
640 gst_app_sink_check_buffer_lists_support (appsink);
641 g_mutex_unlock (priv->mutex);
647 gst_app_sink_stop (GstBaseSink * psink)
649 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
650 GstAppSinkPrivate *priv = appsink->priv;
652 g_mutex_lock (priv->mutex);
653 GST_DEBUG_OBJECT (appsink, "stopping");
654 priv->flushing = TRUE;
655 priv->started = FALSE;
656 gst_app_sink_flush_unlocked (appsink);
657 g_mutex_unlock (priv->mutex);
663 gst_app_sink_event (GstBaseSink * sink, GstEvent * event)
665 GstAppSink *appsink = GST_APP_SINK_CAST (sink);
666 GstAppSinkPrivate *priv = appsink->priv;
668 switch (event->type) {
671 g_mutex_lock (priv->mutex);
672 GST_DEBUG_OBJECT (appsink, "receiving EOS");
674 g_cond_signal (priv->cond);
675 g_mutex_unlock (priv->mutex);
678 if (priv->callbacks.eos)
679 priv->callbacks.eos (appsink, priv->user_data);
681 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_EOS], 0);
684 case GST_EVENT_FLUSH_START:
685 /* we don't have to do anything here, the base class will call unlock
686 * which will make sure we exit the _render method */
687 GST_DEBUG_OBJECT (appsink, "received FLUSH_START");
689 case GST_EVENT_FLUSH_STOP:
690 g_mutex_lock (priv->mutex);
691 GST_DEBUG_OBJECT (appsink, "received FLUSH_STOP");
692 gst_app_sink_flush_unlocked (appsink);
693 g_mutex_unlock (priv->mutex);
702 gst_app_sink_preroll (GstBaseSink * psink, GstBuffer * buffer)
704 GstFlowReturn res = GST_FLOW_OK;
705 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
706 GstAppSinkPrivate *priv = appsink->priv;
709 g_mutex_lock (priv->mutex);
713 GST_DEBUG_OBJECT (appsink, "setting preroll buffer %p", buffer);
714 gst_buffer_replace (&priv->preroll, buffer);
716 g_cond_signal (priv->cond);
717 emit = priv->emit_signals;
718 g_mutex_unlock (priv->mutex);
720 if (priv->callbacks.new_preroll)
721 res = priv->callbacks.new_preroll (appsink, priv->user_data);
723 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_PREROLL], 0);
729 GST_DEBUG_OBJECT (appsink, "we are flushing");
730 g_mutex_unlock (priv->mutex);
731 return GST_FLOW_WRONG_STATE;
736 gst_app_sink_render_common (GstBaseSink * psink, GstMiniObject * data,
740 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
741 GstAppSinkPrivate *priv = appsink->priv;
745 g_mutex_lock (priv->mutex);
749 GST_DEBUG_OBJECT (appsink, "pushing render buffer%s %p on queue (%d)",
750 is_list ? " list" : "", data, priv->queue->length);
752 while (priv->max_buffers > 0 && priv->queue->length >= priv->max_buffers) {
756 /* we need to drop the oldest buffer/list and try again */
757 obj = g_queue_pop_head (priv->queue);
758 GST_DEBUG_OBJECT (appsink, "dropping old buffer/list %p", obj);
759 gst_mini_object_unref (obj);
761 GST_DEBUG_OBJECT (appsink, "waiting for free space, length %d >= %d",
762 priv->queue->length, priv->max_buffers);
765 /* we are asked to unlock, call the wait_preroll method */
766 g_mutex_unlock (priv->mutex);
767 if ((ret = gst_base_sink_wait_preroll (psink)) != GST_FLOW_OK)
770 /* we are allowed to continue now */
774 /* wait for a buffer to be removed or flush */
775 g_cond_wait (priv->cond, priv->mutex);
780 /* we need to ref the buffer when pushing it in the queue */
781 g_queue_push_tail (priv->queue, gst_mini_object_ref (data));
782 g_cond_signal (priv->cond);
783 emit = priv->emit_signals;
784 g_mutex_unlock (priv->mutex);
787 if (priv->callbacks.new_buffer_list)
788 priv->callbacks.new_buffer_list (appsink, priv->user_data);
790 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER_LIST], 0);
792 if (priv->callbacks.new_buffer)
793 priv->callbacks.new_buffer (appsink, priv->user_data);
795 g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER], 0);
801 GST_DEBUG_OBJECT (appsink, "we are flushing");
802 g_mutex_unlock (priv->mutex);
803 return GST_FLOW_WRONG_STATE;
807 GST_DEBUG_OBJECT (appsink, "we are stopping");
813 gst_app_sink_render (GstBaseSink * psink, GstBuffer * buffer)
815 return gst_app_sink_render_common (psink, GST_MINI_OBJECT_CAST (buffer),
820 gst_app_sink_render_list (GstBaseSink * sink, GstBufferList * list)
822 GstBufferListIterator *it;
827 appsink = GST_APP_SINK_CAST (sink);
829 if (appsink->priv->buffer_lists_supported)
830 return gst_app_sink_render_common (sink, GST_MINI_OBJECT_CAST (list), TRUE);
832 /* The application doesn't support buffer lists, extract individual buffers
833 * then and push them one-by-one */
834 GST_INFO_OBJECT (sink, "chaining each group in list as a merged buffer");
836 it = gst_buffer_list_iterate (list);
838 if (gst_buffer_list_iterator_next_group (it)) {
840 group = gst_buffer_list_iterator_merge_group (it);
842 group = gst_buffer_new ();
843 GST_DEBUG_OBJECT (sink, "chaining empty group");
845 GST_DEBUG_OBJECT (sink, "chaining group");
847 flow = gst_app_sink_render (sink, group);
848 gst_buffer_unref (group);
849 } while (flow == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
851 GST_DEBUG_OBJECT (sink, "chaining empty group");
852 group = gst_buffer_new ();
853 flow = gst_app_sink_render (sink, group);
854 gst_buffer_unref (group);
857 gst_buffer_list_iterator_free (it);
863 gst_app_sink_getcaps (GstBaseSink * psink)
866 GstAppSink *appsink = GST_APP_SINK_CAST (psink);
867 GstAppSinkPrivate *priv = appsink->priv;
869 GST_OBJECT_LOCK (appsink);
870 if ((caps = priv->caps))
872 GST_DEBUG_OBJECT (appsink, "got caps %" GST_PTR_FORMAT, caps);
873 GST_OBJECT_UNLOCK (appsink);
878 static GstMiniObject *
879 gst_app_sink_pull_object (GstAppSink * appsink)
881 GstMiniObject *obj = NULL;
882 GstAppSinkPrivate *priv;
884 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
886 priv = appsink->priv;
888 g_mutex_lock (priv->mutex);
891 GST_DEBUG_OBJECT (appsink, "trying to grab a buffer/list");
895 if (!g_queue_is_empty (priv->queue))
901 /* nothing to return, wait */
902 GST_DEBUG_OBJECT (appsink, "waiting for a buffer/list");
903 g_cond_wait (priv->cond, priv->mutex);
905 obj = g_queue_pop_head (priv->queue);
906 GST_DEBUG_OBJECT (appsink, "we have a buffer/list %p", obj);
907 g_cond_signal (priv->cond);
908 g_mutex_unlock (priv->mutex);
912 /* special conditions */
915 GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
916 g_mutex_unlock (priv->mutex);
921 GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
922 g_mutex_unlock (priv->mutex);
930 * gst_app_sink_set_caps:
931 * @appsink: a #GstAppSink
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, you must check the caps
937 * on the buffers to get the actual used caps.
942 gst_app_sink_set_caps (GstAppSink * appsink, const GstCaps * caps)
945 GstAppSinkPrivate *priv;
947 g_return_if_fail (GST_IS_APP_SINK (appsink));
949 priv = appsink->priv;
951 GST_OBJECT_LOCK (appsink);
952 GST_DEBUG_OBJECT (appsink, "setting caps to %" GST_PTR_FORMAT, caps);
953 if ((old = priv->caps) != caps) {
955 priv->caps = gst_caps_copy (caps);
959 gst_caps_unref (old);
961 GST_OBJECT_UNLOCK (appsink);
965 * gst_app_sink_get_caps:
966 * @appsink: a #GstAppSink
968 * Get the configured caps on @appsink.
970 * Returns: the #GstCaps accepted by the sink. gst_caps_unref() after usage.
975 gst_app_sink_get_caps (GstAppSink * appsink)
978 GstAppSinkPrivate *priv;
980 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
982 priv = appsink->priv;
984 GST_OBJECT_LOCK (appsink);
985 if ((caps = priv->caps))
987 GST_DEBUG_OBJECT (appsink, "getting caps of %" GST_PTR_FORMAT, caps);
988 GST_OBJECT_UNLOCK (appsink);
994 * gst_app_sink_is_eos:
995 * @appsink: a #GstAppSink
997 * Check if @appsink is EOS, which is when no more buffers can be pulled because
998 * an EOS event was received.
1000 * This function also returns %TRUE when the appsink is not in the PAUSED or
1003 * Returns: %TRUE if no more buffers can be pulled and the appsink is EOS.
1008 gst_app_sink_is_eos (GstAppSink * appsink)
1011 GstAppSinkPrivate *priv;
1013 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1015 priv = appsink->priv;
1017 g_mutex_lock (priv->mutex);
1021 if (priv->is_eos && g_queue_is_empty (priv->queue)) {
1022 GST_DEBUG_OBJECT (appsink, "we are EOS and the queue is empty");
1025 GST_DEBUG_OBJECT (appsink, "we are not yet EOS");
1028 g_mutex_unlock (priv->mutex);
1034 GST_DEBUG_OBJECT (appsink, "we are stopped, return TRUE");
1035 g_mutex_unlock (priv->mutex);
1041 * gst_app_sink_set_emit_signals:
1042 * @appsink: a #GstAppSink
1043 * @emit: the new state
1045 * Make appsink emit the "new-preroll" and "new-buffer" signals. This option is
1046 * by default disabled because signal emission is expensive and unneeded when
1047 * the application prefers to operate in pull mode.
1052 gst_app_sink_set_emit_signals (GstAppSink * appsink, gboolean emit)
1054 GstAppSinkPrivate *priv;
1056 g_return_if_fail (GST_IS_APP_SINK (appsink));
1058 priv = appsink->priv;
1060 g_mutex_lock (priv->mutex);
1061 priv->emit_signals = emit;
1062 g_mutex_unlock (priv->mutex);
1066 * gst_app_sink_get_emit_signals:
1067 * @appsink: a #GstAppSink
1069 * Check if appsink will emit the "new-preroll" and "new-buffer" signals.
1071 * Returns: %TRUE if @appsink is emitting the "new-preroll" and "new-buffer"
1077 gst_app_sink_get_emit_signals (GstAppSink * appsink)
1080 GstAppSinkPrivate *priv;
1082 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1084 priv = appsink->priv;
1086 g_mutex_lock (priv->mutex);
1087 result = priv->emit_signals;
1088 g_mutex_unlock (priv->mutex);
1094 * gst_app_sink_set_max_buffers:
1095 * @appsink: a #GstAppSink
1096 * @max: the maximum number of buffers to queue
1098 * Set the maximum amount of buffers that can be queued in @appsink. After this
1099 * amount of buffers are queued in appsink, any more buffers will block upstream
1100 * elements until a buffer is pulled from @appsink.
1105 gst_app_sink_set_max_buffers (GstAppSink * appsink, guint max)
1107 GstAppSinkPrivate *priv;
1109 g_return_if_fail (GST_IS_APP_SINK (appsink));
1111 priv = appsink->priv;
1113 g_mutex_lock (priv->mutex);
1114 if (max != priv->max_buffers) {
1115 priv->max_buffers = max;
1116 /* signal the change */
1117 g_cond_signal (priv->cond);
1119 g_mutex_unlock (priv->mutex);
1123 * gst_app_sink_get_max_buffers:
1124 * @appsink: a #GstAppSink
1126 * Get the maximum amount of buffers that can be queued in @appsink.
1128 * Returns: The maximum amount of buffers that can be queued.
1133 gst_app_sink_get_max_buffers (GstAppSink * appsink)
1136 GstAppSinkPrivate *priv;
1138 g_return_val_if_fail (GST_IS_APP_SINK (appsink), 0);
1140 priv = appsink->priv;
1142 g_mutex_lock (priv->mutex);
1143 result = priv->max_buffers;
1144 g_mutex_unlock (priv->mutex);
1150 * gst_app_sink_set_drop:
1151 * @appsink: a #GstAppSink
1152 * @drop: the new state
1154 * Instruct @appsink to drop old buffers when the maximum amount of queued
1155 * buffers is reached.
1160 gst_app_sink_set_drop (GstAppSink * appsink, gboolean drop)
1162 GstAppSinkPrivate *priv;
1164 g_return_if_fail (GST_IS_APP_SINK (appsink));
1166 priv = appsink->priv;
1168 g_mutex_lock (priv->mutex);
1169 if (priv->drop != drop) {
1171 /* signal the change */
1172 g_cond_signal (priv->cond);
1174 g_mutex_unlock (priv->mutex);
1178 * gst_app_sink_get_drop:
1179 * @appsink: a #GstAppSink
1181 * Check if @appsink will drop old buffers when the maximum amount of queued
1182 * buffers is reached.
1184 * Returns: %TRUE if @appsink is dropping old buffers when the queue is
1190 gst_app_sink_get_drop (GstAppSink * appsink)
1193 GstAppSinkPrivate *priv;
1195 g_return_val_if_fail (GST_IS_APP_SINK (appsink), FALSE);
1197 priv = appsink->priv;
1199 g_mutex_lock (priv->mutex);
1200 result = priv->drop;
1201 g_mutex_unlock (priv->mutex);
1207 * gst_app_sink_pull_preroll:
1208 * @appsink: a #GstAppSink
1210 * Get the last preroll buffer in @appsink. This was the buffer that caused the
1211 * appsink to preroll in the PAUSED state. This buffer can be pulled many times
1212 * and remains available to the application even after EOS.
1214 * This function is typically used when dealing with a pipeline in the PAUSED
1215 * state. Calling this function after doing a seek will give the buffer right
1216 * after the seek position.
1218 * Note that the preroll buffer will also be returned as the first buffer
1219 * when calling gst_app_sink_pull_buffer().
1221 * If an EOS event was received before any buffers, this function returns
1222 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1224 * This function blocks until a preroll buffer or EOS is received or the appsink
1225 * element is set to the READY/NULL state.
1227 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
1232 gst_app_sink_pull_preroll (GstAppSink * appsink)
1234 GstBuffer *buf = NULL;
1235 GstAppSinkPrivate *priv;
1237 g_return_val_if_fail (GST_IS_APP_SINK (appsink), NULL);
1239 priv = appsink->priv;
1241 g_mutex_lock (priv->mutex);
1244 GST_DEBUG_OBJECT (appsink, "trying to grab a buffer");
1248 if (priv->preroll != NULL)
1254 /* nothing to return, wait */
1255 GST_DEBUG_OBJECT (appsink, "waiting for the preroll buffer");
1256 g_cond_wait (priv->cond, priv->mutex);
1258 buf = gst_buffer_ref (priv->preroll);
1259 GST_DEBUG_OBJECT (appsink, "we have the preroll buffer %p", buf);
1260 g_mutex_unlock (priv->mutex);
1264 /* special conditions */
1267 GST_DEBUG_OBJECT (appsink, "we are EOS, return NULL");
1268 g_mutex_unlock (priv->mutex);
1273 GST_DEBUG_OBJECT (appsink, "we are stopped, return NULL");
1274 g_mutex_unlock (priv->mutex);
1280 * gst_app_sink_pull_buffer:
1281 * @appsink: a #GstAppSink
1283 * This function blocks until a buffer or EOS becomes available or the appsink
1284 * element is set to the READY/NULL state.
1286 * This function will only return buffers when the appsink is in the PLAYING
1287 * state. All rendered buffers will be put in a queue so that the application
1288 * can pull buffers at its own rate. Note that when the application does not
1289 * pull buffers fast enough, the queued buffers could consume a lot of memory,
1290 * especially when dealing with raw video frames.
1292 * If an EOS event was received before any buffers, this function returns
1293 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1295 * Returns: a #GstBuffer or NULL when the appsink is stopped or EOS.
1301 gst_app_sink_pull_buffer (GstAppSink * appsink)
1303 GST_DEBUG_OBJECT (appsink, "pull a buffer");
1304 return GST_BUFFER_CAST (gst_app_sink_pull_object (appsink));
1308 * gst_app_sink_pull_buffer_list:
1309 * @appsink: a #GstAppSink
1311 * This function blocks until a buffer list or EOS becomes available or the
1312 * appsink element is set to the READY/NULL state.
1314 * This function will only return buffer lists when the appsink is in the
1315 * PLAYING state. All rendered buffer lists will be put in a queue so that
1316 * the application can pull buffer lists at its own rate. Note that when
1317 * the application does not pull buffer lists fast enough, the queued buffer
1318 * lists could consume a lot of memory, especially when dealing with raw
1321 * If an EOS event was received before any buffer lists, this function returns
1322 * %NULL. Use gst_app_sink_is_eos () to check for the EOS condition.
1324 * Returns: a #GstBufferList or NULL when the appsink is stopped or EOS.
1327 gst_app_sink_pull_buffer_list (GstAppSink * appsink)
1329 GST_DEBUG_OBJECT (appsink, "pull a buffer list");
1330 return GST_BUFFER_LIST_CAST (gst_app_sink_pull_object (appsink));
1334 * gst_app_sink_set_callbacks:
1335 * @appsink: a #GstAppSink
1336 * @callbacks: the callbacks
1337 * @user_data: a user_data argument for the callbacks
1338 * @notify: a destroy notify function
1340 * Set callbacks which will be executed for each new preroll, new buffer and eos.
1341 * This is an alternative to using the signals, it has lower overhead and is thus
1342 * less expensive, but also less flexible.
1344 * If callbacks are installed, no signals will be emitted for performance
1350 gst_app_sink_set_callbacks (GstAppSink * appsink,
1351 GstAppSinkCallbacks * callbacks, gpointer user_data, GDestroyNotify notify)
1353 GDestroyNotify old_notify;
1354 GstAppSinkPrivate *priv;
1356 g_return_if_fail (GST_IS_APP_SINK (appsink));
1357 g_return_if_fail (callbacks != NULL);
1359 priv = appsink->priv;
1361 GST_OBJECT_LOCK (appsink);
1362 old_notify = priv->notify;
1367 old_data = priv->user_data;
1369 priv->user_data = NULL;
1370 priv->notify = NULL;
1371 GST_OBJECT_UNLOCK (appsink);
1373 old_notify (old_data);
1375 GST_OBJECT_LOCK (appsink);
1377 priv->callbacks = *callbacks;
1378 priv->user_data = user_data;
1379 priv->notify = notify;
1380 priv->buffer_lists_supported =
1381 gst_app_sink_check_buffer_lists_support (appsink);
1382 GST_OBJECT_UNLOCK (appsink);
1385 /*** GSTURIHANDLER INTERFACE *************************************************/
1388 gst_app_sink_uri_get_type (void)
1390 return GST_URI_SINK;
1394 gst_app_sink_uri_get_protocols (void)
1396 static gchar *protocols[] = { (char *) "appsink", NULL };
1401 static const gchar *
1402 gst_app_sink_uri_get_uri (GstURIHandler * handler)
1408 gst_app_sink_uri_set_uri (GstURIHandler * handler, const gchar * uri)
1413 protocol = gst_uri_get_protocol (uri);
1414 ret = !strcmp (protocol, "appsink");
1421 gst_app_sink_uri_handler_init (gpointer g_iface, gpointer iface_data)
1423 GstURIHandlerInterface *iface = (GstURIHandlerInterface *) g_iface;
1425 iface->get_type = gst_app_sink_uri_get_type;
1426 iface->get_protocols = gst_app_sink_uri_get_protocols;
1427 iface->get_uri = gst_app_sink_uri_get_uri;
1428 iface->set_uri = gst_app_sink_uri_set_uri;