aggregator: Add new GstAggregator base class

This base class has been added to a newly created libgstbadbase library

Co-Authored by: Mathieu Duponchelle <mathieu.duponchelle@opencreed.com>

https://bugzilla.gnome.org/show_bug.cgi?id=731917

configure.ac

@@ -3221,6 +3221,7 @@ gst-libs/gst/codecparsers/Makefile
 gst-libs/gst/mpegts/Makefile
 gst-libs/gst/uridownloader/Makefile
 gst-libs/gst/wayland/Makefile
+gst-libs/gst/base/Makefile
 sys/Makefile
 sys/dshowdecwrapper/Makefile
 sys/acmenc/Makefile
@@ -3359,6 +3360,8 @@ pkgconfig/gstreamer-mpegts.pc
 pkgconfig/gstreamer-mpegts-uninstalled.pc
 pkgconfig/gstreamer-wayland.pc
 pkgconfig/gstreamer-wayland-uninstalled.pc
+pkgconfig/gstreamer-bad-base.pc
+pkgconfig/gstreamer-bad-base-uninstalled.pc
 tools/Makefile
 m4/Makefile
 )

docs/libs/gst-plugins-bad-libs-docs.sgml

@@ -57,6 +57,12 @@
       <xi:include href="xml/gstinsertbin.xml" />
     </chapter>
 
+    <chapter id="base">
+      <title>GStreamer Base classes from gst-plugins-bad</title>
+      <xi:include href="xml/gstaggregator.xml" />
+      <xi:include href="xml/gstaggregatorpad.xml" />
+    </chapter>
+
     <chapter id="gl">
       <title>OpenGL Helper Library</title>
       <xi:include href="xml/gstglapi.xml"/>

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

@@ -1290,3 +1290,38 @@ gst_gl_window_x11_get_type
 GstGLWindowX11Private
 x11_event_source_new
 </SECTION>
+
+<SECTION>
+<FILE>gstaggregator</FILE>
+<TITLE>GstAggregator</TITLE>
+GstAggregator
+GstAggregatorClass
+gst_aggregator_finish_buffer
+gst_aggregator_set_src_caps
+gst_aggregator_iterate_sinkpads
+<SUBSECTION Standard>
+GST_IS_AGGREGATOR
+GST_IS_AGGREGATOR_CLASS
+GST_TYPE_AGGREGATOR
+GST_AGGREGATOR
+GST_AGGREGATOR_CLASS
+GST_AGGREGATOR_GET_CLASS
+gst_aggregator_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gstaggregatorpad</FILE>
+<TITLE>GstAggregatorPad</TITLE>
+GstAggregatorPad
+GstAggregatorPadClass
+gst_aggregator_pad_steal_buffer
+gst_aggregator_pad_get_buffer
+<SUBSECTION Standard>
+GST_IS_AGGREGATOR_PAD
+GST_IS_AGGREGATOR_PAD_CLASS
+GST_TYPE_AGGREGATOR_PAD
+GST_AGGREGATOR_PAD
+GST_AGGREGATOR_PAD_CLASS
+GST_AGGREGATOR_PAD_GET_CLASS
+gst_aggregator_pad_get_type
+</SECTION>

gst-libs/gst/Makefile.am

@@ -11,8 +11,8 @@ WAYLAND_DIR=wayland
 endif
 
 SUBDIRS = interfaces basecamerabinsrc codecparsers \
-	 insertbin uridownloader mpegts $(GL_DIR) $(WAYLAND_DIR)
+	 insertbin uridownloader mpegts base $(GL_DIR) $(WAYLAND_DIR)
 
 noinst_HEADERS = gst-i18n-plugin.h gettext.h glib-compat-private.h
 DIST_SUBDIRS = interfaces gl basecamerabinsrc codecparsers \
-	insertbin uridownloader mpegts wayland
+	insertbin uridownloader mpegts wayland base

gst-libs/gst/base/Makefile.am

@@ -0,0 +1,21 @@
+lib_LTLIBRARIES = libgstbadbase-@GST_API_VERSION@.la
+
+libgstbadbase_@GST_API_VERSION@_la_SOURCES = \
+	gstaggregator.c
+
+libgstbadbase_@GST_API_VERSION@_la_CFLAGS = $(GST_CFLAGS)
+libgstbadbase_@GST_API_VERSION@_la_LIBADD = $(GST_LIBS)
+libgstbadbase_@GST_API_VERSION@_la_LDFLAGS = $(GST_LDFLAGS)
+
+libgstbadbase_@GST_API_VERSION@includedir = $(includedir)/gstreamer-@GST_API_VERSION@/gst/badbase/
+libgstbadbase_@GST_API_VERSION@include_HEADERS =	\
+	gstaggregator.h
+
+EXTRA_DIST = 
+
+CLEANFILES = *.gcno *.gcda *.gcov
+
+%.c.gcov: .libs/libgstbadbase_@GST_API_VERSION@_la-%.gcda %.c
+	$(GCOV) -b -f -o $^ > $@.out
+
+gcov: $(libgstbadbase_@GST_API_VERSION@_la_SOURCES:=.gcov)

gst-libs/gst/base/gstaggregator.h

@@ -0,0 +1,256 @@
+/* GStreamer
+ * Copyright (C) 2014 Mathieu Duponchelle <mathieu.duponchelle@oencreed.com>
+ * Copyright (C) 2014 Thibault Saunier <tsaunier@gnome.org>
+ *
+ * gstaggregator.c:
+ *
+ * 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., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef __GST_AGGREGATOR_H__
+#define __GST_AGGREGATOR_H__
+
+#include <gst/gst.h>
+
+G_BEGIN_DECLS
+
+/**************************
+ * GstAggregator Structs  *
+ *************************/
+
+typedef struct _GstAggregator GstAggregator;
+typedef struct _GstAggregatorPrivate GstAggregatorPrivate;
+typedef struct _GstAggregatorClass GstAggregatorClass;
+
+/************************
+ * GstAggregatorPad API *
+ ***********************/
+
+#define GST_TYPE_AGGREGATOR_PAD            (gst_aggregator_pad_get_type())
+#define GST_AGGREGATOR_PAD(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPad))
+#define GST_AGGREGATOR_PAD_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPadClass))
+#define GST_AGGREGATOR_PAD_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPadClass))
+#define GST_IS_AGGREGATOR_PAD(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AGGREGATOR_PAD))
+#define GST_IS_AGGREGATOR_PAD_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AGGREGATOR_PAD))
+
+/****************************
+ * GstAggregatorPad Structs *
+ ***************************/
+
+typedef struct _GstAggregatorPad GstAggregatorPad;
+typedef struct _GstAggregatorPadClass GstAggregatorPadClass;
+typedef struct _GstAggregatorPadPrivate GstAggregatorPadPrivate;
+
+/**
+ * GstAggregatorPad:
+ * @buffer: currently queued buffer.
+ * @segment: last segment received.
+ *
+ * The implementation the GstPad to use with #GstAggregator
+ */
+struct _GstAggregatorPad
+{
+  GstPad                       parent;
+
+  GstBuffer                 *  buffer;
+  GstSegment                   segment;
+  gboolean                     eos;
+
+  /* < Private > */
+  GstAggregatorPadPrivate   *  priv;
+
+  gpointer _gst_reserved[GST_PADDING];
+};
+
+/**
+ * GstAggregatorPadClass:
+ * @flush:    Optional
+ *            Called when the pad has received a flush stop, this is the place
+ *            to flush any information specific to the pad, it allows for individual
+ *            pads to be flushed while others might not be.
+ *
+ */
+struct _GstAggregatorPadClass
+{
+  GstPadClass   parent_class;
+
+  GstFlowReturn (*flush)     (GstAggregatorPad * aggpad, GstAggregator * aggregator);
+
+  /*< private >*/
+  gpointer      _gst_reserved[GST_PADDING];
+};
+
+GType gst_aggregator_pad_get_type           (void);
+
+/****************************
+ * GstAggregatorPad methods *
+ ***************************/
+
+GstBuffer * gst_aggregator_pad_steal_buffer (GstAggregatorPad *  pad);
+GstBuffer * gst_aggregator_pad_get_buffer   (GstAggregatorPad *  pad);
+
+/*********************
+ * GstAggregator API *
+ ********************/
+
+#define GST_TYPE_AGGREGATOR            (gst_aggregator_get_type())
+#define GST_AGGREGATOR(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AGGREGATOR,GstAggregator))
+#define GST_AGGREGATOR_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AGGREGATOR,GstAggregatorClass))
+#define GST_AGGREGATOR_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_AGGREGATOR,GstAggregatorClass))
+#define GST_IS_AGGREGATOR(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AGGREGATOR))
+#define GST_IS_AGGREGATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AGGREGATOR))
+
+#define GST_FLOW_CUSTOM_SUCCESS        GST_FLOW_NOT_HANDLED
+
+/**
+ * GstAggregator:
+ * @aggregator_pads: #GList of #GstAggregatorPad managed by this #GstAggregator.
+ *
+ * Collectpads object.
+ */
+struct _GstAggregator
+{
+  GstElement               parent;
+
+  GstPad                *  srcpad;
+
+  GstSegment               segment;
+
+  /*< private >*/
+  GstAggregatorPrivate  *  priv;
+
+  gpointer                 _gst_reserved[GST_PADDING];
+};
+
+/**
+ * GstAggregatorClass:
+ * @sinkpads_type:  Optional.
+ *                  The type of the pads that should be created when
+ *                  GstElement.request_new_pad is called.
+ * @flush:          Optional.
+ *                  Called after a succesful flushing seek, once all the flush
+ *                  stops have been received. Flush pad-specific data in
+ *                  #GstAggregatorPad->flush.
+ * @clip:           Optional.
+ *                  Called when a buffer is received on a sink pad, the task
+ *                  of clipping it and translating it to the current segment
+ *                  falls on the subclass.
+ * @sink_event:     Optional.
+ *                  Called when an event is received on a sink pad, the subclass
+ *                  should always chain up.
+ * @sink_query:     Optional.
+ *                  Called when a query is received on a sink pad, the subclass
+ *                  should always chain up.
+ * @src_event:      Optional.
+ *                  Called when an event is received on the src pad, the subclass
+ *                  should always chain up.
+ * @src_query:      Optional.
+ *                  Called when a query is received on the src pad, the subclass
+ *                  should always chain up.
+ * @src_activate:   Optional.
+ *                  Called when the src pad is activated, it will start/stop its
+ *                  pad task right after that call.
+ * @aggregate:      Mandatory.
+ *                  Called when buffers are queued on all sinkpads. Classes
+ *                  should iterate the GstElement->sinkpads and peek or steal
+ *                  buffers from the #GstAggregatorPads. If the subclass returns
+ *                  GST_FLOW_EOS, sending of the eos event will be taken care
+ *                  of. Once / if a buffer has been constructed from the
+ *                  aggregated buffers, the subclass should call _finish_buffer.
+ * @stop:           Optional.
+ *                  Should be linked up first. Called when the
+ *                  element goes from PAUSED to READY. The subclass should free
+ *                  all resources and reset its state.
+ * @start:          Optional.
+ *                  Should be linked up first. Called when the element goes from
+ *                  READY to PAUSED. The subclass should get ready to process
+ *                  aggregated buffers.
+ *
+ * The aggregator base class will handle in a thread-safe way all manners of
+ * concurrent flushes, seeks, pad additions and removals, leaving to the
+ * subclass the responsibility of clipping buffers, and aggregating buffers in
+ * the way the implementor sees fit.
+ *
+ * It will also take care of event ordering (stream-start, segment, eos).
+ *
+ * Basically, a basic implementation will override @aggregate, and call
+ * _finish_buffer from inside that function.
+ */
+struct _GstAggregatorClass {
+  GstElementClass   parent_class;
+
+  GType             sinkpads_type;
+
+  GstFlowReturn     (*flush)          (GstAggregator    *  aggregator);
+
+  GstFlowReturn     (*clip)           (GstAggregator    *  agg,
+                                       GstAggregatorPad *  bpad,
+                                       GstBuffer        *  buf,
+                                       GstBuffer        ** outbuf);
+
+  /* sinkpads virtual methods */
+  gboolean          (*sink_event)     (GstAggregator    *  aggregate,
+                                       GstAggregatorPad *  bpad,
+                                       GstEvent         *  event);
+
+  gboolean          (*sink_query)     (GstAggregator    *  aggregate,
+                                       GstAggregatorPad *  bpad,
+                                       GstQuery         *  query);
+
+  /* srcpad virtual methods */
+  gboolean          (*src_event)      (GstAggregator    *  aggregate,
+                                       GstEvent         *  event);
+
+  gboolean          (*src_query)      (GstAggregator    *  aggregate,
+                                       GstQuery         *  query);
+
+  gboolean          (*src_activate)   (GstAggregator    *  aggregator,
+                                       GstPadMode          mode,
+                                       gboolean            active);
+
+  GstFlowReturn     (*aggregate)      (GstAggregator    *  aggregator);
+
+  gboolean          (*stop)           (GstAggregator    *  aggregator);
+
+  gboolean          (*start)          (GstAggregator    *  aggregator);
+
+  /*< private >*/
+  gpointer          _gst_reserved[GST_PADDING];
+};
+
+/*************************
+ * GstAggregator methods *
+ ************************/
+
+GstFlowReturn  gst_aggregator_finish_buffer         (GstAggregator                *  agg,
+                                                     GstBuffer                    *  buffer);
+void           gst_aggregator_set_src_caps          (GstAggregator                *  agg,
+                                                     GstCaps                      *  caps);
+
+GType gst_aggregator_get_type(void);
+
+/* API that should eventually land in GstElement itself*/
+typedef gboolean (*GstAggregatorPadForeachFunc)    (GstAggregator                 *  self,
+                                                    GstPad                        *  pad,
+                                                    gpointer                         user_data);
+gboolean gst_aggregator_iterate_sinkpads           (GstAggregator                 *  self,
+                                                    GstAggregatorPadForeachFunc      func,
+                                                    gpointer                         user_data);
+
+
+G_END_DECLS
+
+#endif /* __GST_AGGREGATOR_H__ */

pkgconfig/gstreamer-bad-base-uninstalled.pc.in

@@ -0,0 +1,15 @@
+prefix=
+exec_prefix=
+libdir=${pcfiledir}/../gst-libs/gst/base
+includedir=${pcfiledir}/../gst-libs
+pluginsdir=${pcfiledir}/..
+
+Name: GStreamer bad base classes, uninstalled
+Description: Bad base classes for GStreamer elements, Not Installed
+Version: @VERSION@
+Requires: gstreamer-@GST_API_VERSION@
+
+Libs: -L${libdir} ${libdir}/libgstbadbase-@GST_API_VERSION@.la @BADBASE_LIBS@
+Cflags: -I${includedir} -I@srcdir@/.. @BADBASE_CFLAGS@
+
+libraries=badbase

pkgconfig/gstreamer-bad-base.pc.in

@@ -0,0 +1,15 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@/gstreamer-@GST_API_VERSION@
+pluginsdir=@libdir@/gstreamer-@GST_API_VERSION@
+
+Name: GStreamer bad base classes, uninstalled
+Description: Bad base classes for GStreamer elements, Not Installed
+Version: @VERSION@
+Requires: gstreamer-@GST_API_VERSION@
+
+Libs: -L${libdir} ${libdir}/libgstbadbase-@GST_API_VERSION@.la @BADBASE_LIBS@
+Cflags: -I${includedir} -I@srcdir@/.. @BADBASE_CFLAGS@
+
+libraries=badbase

tests/check/Makefile.am

@@ -244,6 +244,7 @@ check_PROGRAMS = \
 	libs/mpegts \
 	libs/h264parser \
 	libs/vp8parser \
+	libs/aggregator \
 	$(check_uvch264) \
 	libs/vc1parser \
 	$(check_schro) \
@@ -455,6 +456,16 @@ libs_gstglupload_LDADD = \
 	$(GST_PLUGINS_BASE_LIBS) -lgstvideo-$(GST_API_VERSION) \
 	$(GST_BASE_LIBS) $(GST_LIBS) $(LDADD)
 
+libs_aggregator_LDADD = \
+	$(top_builddir)/gst-libs/gst/base/libgstbadbase-@GST_API_VERSION@.la \
+	$(GST_PLUGINS_BASE_LIBS) \
+	$(GST_BASE_LIBS) $(GST_LIBS) $(LDADD)
+
+libs_aggregator_CFLAGS = \
+	$(GST_PLUGINS_BAD_CFLAGS) $(GST_PLUGINS_BASE_CFLAGS) \
+	-DGST_USE_UNSTABLE_API \
+	$(GST_BASE_CFLAGS) $(GST_CFLAGS) $(AM_CFLAGS)
+
 distclean-local-orc:
 	rm -rf orc