Add method to install callbacks on appsink

Based on pacth by Martin Samuelsson <martin dot samuelsson at axis dot com>
Fixes #571299.

Add gst_app_sink_set_callbacks() to install a set of callbacks. This is a more
performant alternative to connecting to the signals.

Add a unit test for appsink.

Clean up some of the appsink docs.

API: GstAppSink::gst_app_sink_set_callbacks()

docs/libs/gst-plugins-base-libs-sections.txt

@@ -25,7 +25,16 @@ GST_TYPE_APP_SRC
 gst_app_src_get_type
 GST_APP_SRC_CLASS
 GST_IS_APP_SRC_CLASS
+GST_APP_BUFFER
+GST_APP_BUFFER_CLASS
+GST_IS_APP_BUFFER
+GST_IS_APP_BUFFER_CLASS
+GST_TYPE_APP_BUFFER
 <SUBSECTION Private>
+GstAppSrcPrivate
+GstAppBuffer
+GstAppBufferClass
+GstAppBufferFinalizeFunc
 gst_app_buffer_get_type
 gst_app_buffer_new
 gst_app_marshal_BOOLEAN__UINT64
@@ -50,7 +59,10 @@ gst_app_sink_set_drop
 gst_app_sink_get_drop
 gst_app_sink_pull_preroll
 gst_app_sink_pull_buffer
+GstAppSinkCallbacks
+gst_app_sink_set_callbacks
 <SUBSECTION Standard>
+GstAppSinkPrivate
 GstAppSinkClass
 GST_APP_SINK
 GST_IS_APP_SINK

gst-libs/gst/app/gstappsink.c

@@ -103,6 +103,10 @@ struct _GstAppSinkPrivate
   gboolean flushing;
   gboolean started;
   gboolean is_eos;
+
+  GstAppSinkCallbacks callbacks;
+  gpointer user_data;
+  GDestroyNotify notify;
 };
 
 GST_DEBUG_CATEGORY_STATIC (app_sink_debug);
@@ -400,6 +404,12 @@ gst_app_sink_dispose (GObject * obj)
     gst_caps_unref (appsink->priv->caps);
     appsink->priv->caps = NULL;
   }
+  if (appsink->priv->notify) {
+    appsink->priv->notify (appsink->priv->user_data);
+  }
+  appsink->priv->user_data = NULL;
+  appsink->priv->notify = NULL;
+
   GST_OBJECT_UNLOCK (appsink);
 
   g_mutex_lock (appsink->priv->mutex);
@@ -571,6 +581,9 @@ gst_app_sink_event (GstBaseSink * sink, GstEvent * event)
 
       /* emit EOS now */
       g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_EOS], 0);
+
+      if (appsink->priv->callbacks.eos)
+        appsink->priv->callbacks.eos (appsink, appsink->priv->user_data);
       break;
     case GST_EVENT_FLUSH_START:
       /* we don't have to do anything here, the base class will call unlock
@@ -608,6 +621,9 @@ gst_app_sink_preroll (GstBaseSink * psink, GstBuffer * buffer)
   if (emit)
     g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_PREROLL], 0);
 
+  if (appsink->priv->callbacks.new_preroll)
+    appsink->priv->callbacks.new_preroll (appsink, appsink->priv->user_data);
+
   return GST_FLOW_OK;
 
 flushing:
@@ -658,6 +674,9 @@ gst_app_sink_render (GstBaseSink * psink, GstBuffer * buffer)
   if (emit)
     g_signal_emit (appsink, gst_app_sink_signals[SIGNAL_NEW_BUFFER], 0);
 
+  if (appsink->priv->callbacks.new_buffer)
+    appsink->priv->callbacks.new_buffer (appsink, appsink->priv->user_data);
+
   return GST_FLOW_OK;
 
 flushing:
@@ -1073,3 +1092,48 @@ not_started:
     return NULL;
   }
 }
+
+/**
+ * gst_app_sink_set_callbacks:
+ * @appsink: a #GstAppSink
+ * @callbacks: the callbacks
+ * @user_data: a user_data argument for the callbacks
+ * @notify: a destroy notify function
+ *
+ * Set callbacks which will be executed for each new preroll, new buffer and eos.
+ * This is an alternative to using the signals, it has lower overhead and is thus
+ * less expensive, but also less flexible.
+ *
+ * Since: 0.10.23
+ */
+void
+gst_app_sink_set_callbacks (GstAppSink * appsink,
+    GstAppSinkCallbacks * callbacks, gpointer user_data, GDestroyNotify notify)
+{
+  GDestroyNotify old_notify;
+
+  g_return_if_fail (appsink != NULL);
+  g_return_if_fail (GST_IS_APP_SINK (appsink));
+  g_return_if_fail (callbacks != NULL);
+
+  GST_OBJECT_LOCK (appsink);
+  old_notify = appsink->priv->notify;
+
+  if (old_notify) {
+    gpointer old_data;
+
+    old_data = appsink->priv->user_data;
+
+    appsink->priv->user_data = NULL;
+    appsink->priv->notify = NULL;
+    GST_OBJECT_UNLOCK (appsink);
+
+    old_notify (old_data);
+
+    GST_OBJECT_LOCK (appsink);
+  }
+  appsink->priv->callbacks = *callbacks;
+  appsink->priv->user_data = user_data;
+  appsink->priv->notify = notify;
+  GST_OBJECT_UNLOCK (appsink);
+}

gst-libs/gst/app/gstappsink.h

@@ -40,6 +40,32 @@ typedef struct _GstAppSink GstAppSink;
 typedef struct _GstAppSinkClass GstAppSinkClass;
 typedef struct _GstAppSinkPrivate GstAppSinkPrivate;
 
+/**
+ * GstAppSinkCallbacks:
+ * @eos: Signal that the end-of-stream has been reached. This signal is
+ *       emited from the steaming thread.
+ * @new_preroll: Signal that a new preroll buffer is available. 
+ *       This signal is emited from the steaming thread.
+ *       The new preroll buffer can be retrieved with
+ *       gst_app_sink_pull_preroll() either from this callback
+ *       or from any other thread.
+ * @new_buffer: Signal that a new buffer is available. 
+ *       This signal is emited from the steaming thread.
+ *       The new buffer can be retrieved with
+ *       gst_app_sink_pull_buffer() either from this callback
+ *       or from any other thread.
+ *
+ * A set of callbacks that can be installed on the appsink with
+ * gst_app_sink_set_callbacks().
+ *
+ * Since: 0.10.23
+ */
+typedef struct {
+  void (*eos)           (GstAppSink *sink, gpointer user_data);
+  void (*new_preroll)   (GstAppSink *sink, gpointer user_data);
+  void (*new_buffer)    (GstAppSink *sink, gpointer user_data);
+} GstAppSinkCallbacks;
+
 struct _GstAppSink
 {
   GstBaseSink basesink;
@@ -56,9 +82,9 @@ struct _GstAppSinkClass
   GstBaseSinkClass basesink_class;
 
   /* signals */
-  gboolean    (*eos)          (GstAppSink *sink);
+  void        (*eos)          (GstAppSink *sink);
-  gboolean    (*new_preroll)  (GstAppSink *sink);
+  void        (*new_preroll)  (GstAppSink *sink);
-  gboolean    (*new_buffer)   (GstAppSink *sink);
+  void        (*new_buffer)   (GstAppSink *sink);
 
   /* actions */
   GstBuffer * (*pull_preroll)  (GstAppSink *sink);
@@ -87,6 +113,11 @@ gboolean        gst_app_sink_get_drop         (GstAppSink *appsink);
 GstBuffer *     gst_app_sink_pull_preroll     (GstAppSink *appsink);
 GstBuffer *     gst_app_sink_pull_buffer      (GstAppSink *appsink);
 
+void            gst_app_sink_set_callbacks    (GstAppSink * appsink,
+                                               GstAppSinkCallbacks *callbacks,
+					       gpointer user_data,
+					       GDestroyNotify notify);
+
 G_END_DECLS
 
 #endif

tests/check/Makefile.am

@@ -89,6 +89,7 @@ check_PROGRAMS = \
 	$(check_vorbis) \
 	$(check_theora) \
 	elements/adder	\
+	elements/appsink	\
 	elements/audioconvert \
 	elements/audiorate \
 	elements/audioresample \
@@ -204,6 +205,14 @@ libs_pbutils_CFLAGS = \
 libs_pbutils_LDADD = \
 	$(top_builddir)/gst-libs/gst/pbutils/libgstpbutils-@GST_MAJORMINOR@.la $(LDADD)
 
+elements_appsink_CFLAGS = \
+	$(GST_PLUGINS_BASE_CFLAGS) \
+	$(AM_CFLAGS)
+
+elements_appsink_LDADD = \
+	$(top_builddir)/gst-libs/gst/app/libgstapp-@GST_MAJORMINOR@.la \
+	$(LDADD)
+
 elements_alsa_CFLAGS = \
 	$(GST_PLUGINS_BASE_CFLAGS) \
 	$(AM_CFLAGS)

tests/check/elements/.gitignore

@@ -1,6 +1,7 @@
 .dirstamp
 adder
 alsa
+appsink
 audioconvert
 audiorate
 audioresample

tests/check/elements/appsink.c

@@ -0,0 +1,232 @@
+/* GStreamer
+ *
+ * Copyright (C) 2009, Axis Communications AB, LUND, SWEDEN
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <gst/check/gstcheck.h>
+#include <gst-libs/gst/app/gstappsink.h>
+
+gint global_testdata;
+
+static GstPad *mysrcpad;
+
+static GstStaticPadTemplate srctemplate = GST_STATIC_PAD_TEMPLATE ("src",
+    GST_PAD_SRC,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS ("application/x-gst-check")
+    );
+
+static GstElement *
+setup_appsink (void)
+{
+  GstElement *appsink;
+
+  GST_DEBUG ("setup_appsink");
+  appsink = gst_check_setup_element ("appsink");
+  mysrcpad = gst_check_setup_src_pad (appsink, &srctemplate, NULL);
+
+  return appsink;
+}
+
+static void
+cleanup_appsink (GstElement * appsink)
+{
+  GST_DEBUG ("cleanup_appsink");
+
+  gst_check_teardown_src_pad (appsink);
+  gst_check_teardown_element (appsink);
+}
+
+/* This function does an operation to it's indata argument and returns it.
+ * The exact operation performed doesn't matter. Currently it multiplies with
+ * two, but it could do anything. The idea is to use the function to verify
+ * that the code calling it gets run. */
+gint
+operate_on_data (gint indata)
+{
+  return indata * 2;
+}
+
+void
+notify_test_function (gpointer userdata)
+{
+  global_testdata = operate_on_data (GPOINTER_TO_INT (userdata));
+}
+
+void
+callback_function (GstAppSink * appsink, gpointer callback_data)
+{
+  global_testdata = operate_on_data (*((gint *) callback_data));
+}
+
+void
+notify_function (gpointer callback_data)
+{
+  global_testdata = operate_on_data (*((gint *) callback_data));
+}
+
+GST_START_TEST (test_non_clients)
+{
+  GstElement *sink;
+  GstBuffer *buffer;
+  GstCaps *caps;
+
+  sink = setup_appsink ();
+
+  ASSERT_SET_STATE (sink, GST_STATE_PLAYING, GST_STATE_CHANGE_ASYNC);
+
+  caps = gst_caps_from_string ("application/x-gst-check");
+  buffer = gst_buffer_new_and_alloc (4);
+  gst_buffer_set_caps (buffer, caps);
+  gst_caps_unref (caps);
+  fail_unless (gst_pad_push (mysrcpad, buffer) == GST_FLOW_OK);
+
+  GST_DEBUG ("cleaning up appsink");
+  ASSERT_SET_STATE (sink, GST_STATE_NULL, GST_STATE_CHANGE_SUCCESS);
+  cleanup_appsink (sink);
+}
+
+GST_END_TEST;
+
+/* Verifies that the handoff callback gets run one time when passing a buffer */
+GST_START_TEST (test_handoff_callback)
+{
+  GstElement *sink;
+  GstBuffer *buffer;
+  GstCaps *caps;
+  gint testdata;
+  GstAppSinkCallbacks callbacks = { NULL };
+
+  sink = setup_appsink ();
+
+  global_testdata = 0;
+  testdata = 5;                 /* Arbitrary value */
+
+  callbacks.new_buffer = callback_function;
+
+  gst_app_sink_set_callbacks (GST_APP_SINK (sink), &callbacks, &testdata, NULL);
+
+  ASSERT_SET_STATE (sink, GST_STATE_PLAYING, GST_STATE_CHANGE_ASYNC);
+
+  caps = gst_caps_from_string ("application/x-gst-check");
+  buffer = gst_buffer_new_and_alloc (4);
+  gst_buffer_set_caps (buffer, caps);
+  gst_caps_unref (caps);
+  /* Pushing a buffer should run our callback */
+  fail_unless (gst_pad_push (mysrcpad, buffer) == GST_FLOW_OK);
+
+  testdata = operate_on_data (testdata);
+
+  /* If both test_data & global_testdata have been operated on, we're happy. */
+  fail_unless (testdata == global_testdata);
+
+  GST_DEBUG ("cleaning up appsink");
+  ASSERT_SET_STATE (sink, GST_STATE_NULL, GST_STATE_CHANGE_SUCCESS);
+  cleanup_appsink (sink);
+}
+
+GST_END_TEST;
+
+/* Verifies that the notify function gets executed when the sink is destroyed */
+GST_START_TEST (test_notify0)
+{
+  GstElement *sink;
+  gint testdata;
+  GstAppSinkCallbacks callbacks = { NULL };
+
+  sink = gst_element_factory_make ("appsink", NULL);
+
+  global_testdata = 0;
+  testdata = 17;                /* Arbitrary value */
+
+  gst_app_sink_set_callbacks (GST_APP_SINK (sink), &callbacks,
+      &testdata, (*notify_function));
+
+  GST_DEBUG ("cleaning up appsink");
+  /* Destroying sink should call our notify_function */
+  gst_object_unref (sink);
+
+  testdata = operate_on_data (testdata);
+
+  /* If both test_data & global_testdata have been operated on, we're happy. */
+  fail_unless (testdata == global_testdata);
+}
+
+GST_END_TEST;
+
+
+/* Verifies that the notify function gets executed when
+ * gst_app_sink_set_callbacks () gets called */
+GST_START_TEST (test_notify1)
+{
+  GstElement *sink;
+  gint testdata;
+  GstAppSinkCallbacks callbacks = { NULL };
+
+  sink = gst_element_factory_make ("appsink", NULL);
+
+  global_testdata = 0;
+  testdata = 42;                /* Arbitrary value */
+
+  gst_app_sink_set_callbacks (GST_APP_SINK (sink), &callbacks,
+      &testdata, (*notify_function));
+  gst_app_sink_set_callbacks (GST_APP_SINK (sink), &callbacks, &testdata, NULL);
+
+  testdata = operate_on_data (testdata);
+
+  /* If both test_data & global_testdata have been operated on, we're happy. */
+  fail_unless (testdata == global_testdata);
+
+  GST_DEBUG ("cleaning up appsink");
+  /* Destroying sink should call our notify_function */
+  gst_object_unref (sink);
+}
+
+GST_END_TEST;
+
+static Suite *
+appsink_suite (void)
+{
+  Suite *s = suite_create ("appsink");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+  tcase_add_test (tc_chain, test_non_clients);
+  tcase_add_test (tc_chain, test_handoff_callback);
+  tcase_add_test (tc_chain, test_notify0);
+  tcase_add_test (tc_chain, test_notify1);
+
+  return s;
+}
+
+int
+main (int argc, char **argv)
+{
+  int nf;
+
+  Suite *s = appsink_suite ();
+  SRunner *sr = srunner_create (s);
+
+  gst_check_init (&argc, &argv);
+
+  srunner_run_all (sr, CK_NORMAL);
+  nf = srunner_ntests_failed (sr);
+  srunner_free (sr);
+
+  return nf;
+}