cairooverlay: Add generic Cairo overlay video element.

Allows applications to connect to the "draw" signal of
the element and do their custom drawing there.
Includes an example application demonstrating usage.

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

configure.ac

@@ -715,6 +715,13 @@ AG_GST_CHECK_FEATURE(CAIRO, [Cairo graphics rendering], cairo, [
   AG_GST_PKG_CHECK_MODULES(CAIRO, cairo >= 1.0.0)
 ])
 
+dnl *** cairo-gobject ***
+translit(dnm, m, l) AM_CONDITIONAL(USE_CAIRO_GOBJECT, true)
+AG_GST_CHECK_FEATURE(CAIRO_GOBJECT, 
+  [Cairo graphics rendering gobject bindings], cairooverlay, [
+  AG_GST_PKG_CHECK_MODULES(CAIRO_GOBJECT, cairo-gobject >= 1.10.0)
+])
+
 dnl **** ESound ****
 translit(dnm, m, l) AM_CONDITIONAL(USE_ESD, true)
 AG_GST_CHECK_FEATURE(ESD, [ESounD sound daemon], esdsink, [
@@ -1021,6 +1028,7 @@ AM_CONDITIONAL(USE_AALIB, false)
 AM_CONDITIONAL(USE_ANNODEX, false)
 AM_CONDITIONAL(USE_BZ2, false)
 AM_CONDITIONAL(USE_CAIRO, false)
+AM_CONDITIONAL(USE_CAIRO_GOBJECT, false)
 AM_CONDITIONAL(USE_DIRECTSOUND, false)
 AM_CONDITIONAL(USE_DV1394, false)
 AM_CONDITIONAL(USE_ESD, false)
@@ -1191,6 +1199,7 @@ tests/Makefile
 tests/check/Makefile
 tests/examples/Makefile
 tests/examples/audiofx/Makefile
+tests/examples/cairo/Makefile
 tests/examples/equalizer/Makefile
 tests/examples/jack/Makefile
 tests/examples/level/Makefile

docs/plugins/Makefile.am

@@ -81,6 +81,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/cairo/gsttextoverlay.h \
 	$(top_srcdir)/ext/cairo/gsttimeoverlay.h \
 	$(top_srcdir)/ext/cairo/gstcairorender.h \
+	$(top_srcdir)/ext/cairo/gstcairooverlay.h \
 	$(top_srcdir)/ext/dv/gstdvdec.h \
 	$(top_srcdir)/ext/dv/gstdvdemux.h \
 	$(top_srcdir)/ext/esd/esdsink.h \

docs/plugins/gst-plugins-good-plugins-docs.sgml

@@ -51,6 +51,7 @@
     <xi:include href="xml/element-cairotextoverlay.xml" />
     <xi:include href="xml/element-cairotimeoverlay.xml" />
     <xi:include href="xml/element-cairorender.xml" />
+    <xi:include href="xml/element-cairooverlay.xml" />
     <xi:include href="xml/element-capssetter.xml" />
     <xi:include href="xml/element-cmmldec.xml" />
     <xi:include href="xml/element-cmmlenc.xml" />

docs/plugins/gst-plugins-good-plugins-sections.txt

@@ -465,6 +465,18 @@ GST_CAIRO_RENDER_CLASS
 gst_cairo_render_get_type
 </SECTION>
 
+<SECTION>
+<FILE>element-cairooverlay</FILE>
+<TITLE>cairooverlay</TITLE>
+GstCairoOverlay
+<SUBSECTION Standard>
+GstCairoOverlayClass
+GST_TYPE_CAIRO_OVERLAY
+GST_CAIRO_OVERLAY
+GST_CAIRO_OVERLAY_CLASS
+gst_cairo_overlay_get_type
+</SECTION>
+
 <SECTION>
 <FILE>element-capssetter</FILE>
 <TITLE>capssetter</TITLE>

ext/cairo/.gitignore

@@ -0,0 +1,2 @@
+gstcairo-marshal.c
+gstcairo-marshal.h

ext/cairo/Makefile.am

@@ -1,20 +1,45 @@
 plugin_LTLIBRARIES = libgstcairo.la
 
-noinst_HEADERS = gsttimeoverlay.h gsttextoverlay.h gstcairorender.h
+if USE_CAIRO_GOBJECT
+glib_enum_define = GST_CAIRO
+glib_gen_prefix = gst_cairo
+glib_gen_basename = gstcairo
 
+include $(top_srcdir)/common/gst-glib-gen.mak
+
+built_sources = gstcairo-marshal.c
+built_headers = gstcairo-marshal.h
+
+BUILT_SOURCES = $(built_sources) $(built_headers)
+
+gstcairo_gobject_dep_sources = gstcairooverlay.c
+gstcairo_gobject_dep_headers = gstcairooverlay.h
+
+CLEANFILES = $(BUILT_SOURCES)
+endif
+
+noinst_HEADERS = \
+	gsttimeoverlay.h \
+	gsttextoverlay.h \
+	gstcairorender.h \
+	$(gstcairo_gobject_dep_headers)
 libgstcairo_la_SOURCES = \
 	gstcairo.c \
 	gsttimeoverlay.c \
 	gsttextoverlay.c \
-	gstcairorender.c
+	gstcairorender.c \
-
+	$(gstcairo_gobject_dep_sources)
+nodist_libgstcairo_la_SOURCES = \
+    $(built_sources)
 libgstcairo_la_CFLAGS = \
-        $(GST_PLUGINS_BASE_CFLAGS) \
+	$(GST_PLUGINS_BASE_CFLAGS) \
 	$(GST_BASE_CFLAGS) \
-	$(GST_CFLAGS) $(CAIRO_CFLAGS)
+	$(GST_CFLAGS) $(CAIRO_CFLAGS) $(CAIRO_GOBJECT_CFLAGS)
 libgstcairo_la_LIBADD = \
-  $(GST_BASE_LIBS) \
+	$(GST_BASE_LIBS) -lgstvideo-$(GST_MAJORMINOR) \
-  $(GST_LIBS) $(CAIRO_LIBS) $(LIBM)
+	$(GST_LIBS) $(CAIRO_LIBS) $(CAIRO_GOBJECT_LIBS) $(LIBM)
 libgstcairo_la_LDFLAGS = $(GST_PLUGIN_LDFLAGS)
 libgstcairo_la_LIBTOOLFLAGS = --tag=disable-static
 
+EXTRA_DIST = cairo-marshal.list
+

ext/cairo/gstcairo-marshal.list

@@ -0,0 +1,2 @@
+VOID:BOXED,UINT64,UINT64
+VOID:BOXED

ext/cairo/gstcairo.c

@@ -25,6 +25,11 @@
 #include <gsttimeoverlay.h>
 #include <gsttextoverlay.h>
 #include <gstcairorender.h>
+
+#ifdef HAVE_CAIRO_GOBJECT
+#include <gstcairooverlay.h>
+#endif
+
 #include <string.h>
 #include <math.h>
 
@@ -37,6 +42,10 @@ plugin_init (GstPlugin * plugin)
       GST_TYPE_CAIRO_TEXT_OVERLAY);
   gst_element_register (plugin, "cairotimeoverlay", GST_RANK_NONE,
       GST_TYPE_CAIRO_TIME_OVERLAY);
+#ifdef HAVE_CAIRO_GOBJECT
+  gst_element_register (plugin, "cairooverlay", GST_RANK_NONE,
+      GST_TYPE_CAIRO_OVERLAY);
+#endif
   gst_element_register (plugin, "cairorender", GST_RANK_SECONDARY,
       GST_TYPE_CAIRO_RENDER);
 

ext/cairo/gstcairooverlay.c

@@ -0,0 +1,245 @@
+/* GStreamer
+ * Copyright (C) <2011> Jon Nordby <jononor@gmail.com>
+ *
+ * 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.
+ */
+
+/**
+ * SECTION:element-cairooverlay
+ *
+ * cairooverlay renders an overlay using a application provided render function.
+ *
+ * The full example can be found in tests/examples/cairo/cairo_overlay.c
+ * <refsect2>
+ * <title>Example code</title>
+ * |[
+ *
+ * #include &lt;gst/gst.h&gt;
+ * #include &lt;gst/video/video.h&gt;
+ *
+ * ...
+ *
+ * typedef struct {
+ *   gboolean valid;
+ *   int width;
+ *   int height;
+ * } CairoOverlayState;
+ * 
+ * ...
+ *
+ * static void
+ * prepare_overlay (GstElement * overlay, GstCaps * caps, gpointer user_data)
+ * {
+ *   CairoOverlayState *state = (CairoOverlayState *)user_data;
+ *
+ *   gst_video_format_parse_caps (caps, NULL, &amp;state-&gt;width, &amp;state-&gt;height);
+ *   state-&gt;valid = TRUE;
+ * }
+ *
+ * static void
+ * draw_overlay (GstElement * overlay, cairo_t * cr, guint64 timestamp, 
+ *   guint64 duration, gpointer user_data)
+ * {
+ *   CairoOverlayState *s = (CairoOverlayState *)user_data;
+ *   double scale;
+ *
+ *   if (!s-&gt;valid)
+ *     return;
+ *
+ *   scale = 2*(((timestamp/(int)1e7) % 70)+30)/100.0;
+ *   cairo_translate(cr, s-&gt;width/2, (s-&gt;height/2)-30);
+ *   cairo_scale (cr, scale, scale);
+ *
+ *   cairo_move_to (cr, 0, 0);
+ *   cairo_curve_to (cr, 0,-30, -50,-30, -50,0);
+ *   cairo_curve_to (cr, -50,30, 0,35, 0,60 );
+ *   cairo_curve_to (cr, 0,35, 50,30, 50,0 ); *  
+ *   cairo_curve_to (cr, 50,-30, 0,-30, 0,0 );
+ *   cairo_set_source_rgba (cr, 0.9, 0.0, 0.1, 0.7);
+ *   cairo_fill (cr);
+ * }
+ *
+ * ...
+ *
+ * cairo_overlay = gst_element_factory_make (&quot;cairooverlay&quot;, &quot;overlay&quot;);
+ *
+ * g_signal_connect (cairo_overlay, &quot;draw&quot;, G_CALLBACK (draw_overlay),
+ *   overlay_state);
+ * g_signal_connect (cairo_overlay, &quot;caps-changed&quot;, 
+ *   G_CALLBACK (prepare_overlay), overlay_state);
+ * ...
+ *
+ * ]|
+ * </refsect2>
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "gstcairooverlay.h"
+#include "gstcairo-marshal.h"
+
+#include <gst/video/video.h>
+
+#include <cairo.h>
+
+#if G_BYTE_ORDER == G_LITTLE_ENDIAN
+#define ARGB_CAPS GST_VIDEO_CAPS_BGRx " ; " GST_VIDEO_CAPS_BGRA " ; "
+#else
+#define ARGB_CAPS GST_VIDEO_CAPS_xRGB " ; " GST_VIDEO_CAPS_ARGB " ; "
+
+#endif
+
+static GstStaticPadTemplate gst_cairo_overlay_src_template =
+GST_STATIC_PAD_TEMPLATE ("src",
+    GST_PAD_SRC,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS (ARGB_CAPS)
+    );
+
+static GstStaticPadTemplate gst_cairo_overlay_sink_template =
+GST_STATIC_PAD_TEMPLATE ("sink",
+    GST_PAD_SINK,
+    GST_PAD_ALWAYS,
+    GST_STATIC_CAPS (ARGB_CAPS)
+    );
+
+
+GST_BOILERPLATE (GstCairoOverlay, gst_cairo_overlay, GstVideoFilter,
+    GST_TYPE_VIDEO_FILTER);
+
+enum
+{
+  SIGNAL_DRAW,
+  SIGNAL_CAPS_CHANGED,
+  N_SIGNALS
+};
+static guint gst_cairo_overlay_signals[N_SIGNALS];
+
+static gboolean
+gst_cairo_overlay_set_caps (GstBaseTransform * btrans, GstCaps * incaps,
+    GstCaps * outcaps)
+{
+  GstCairoOverlay *overlay = GST_CAIRO_OVERLAY (btrans);
+  GstStructure *s = gst_caps_get_structure (incaps, 0);
+
+  if (!gst_structure_get_int (s, "bpp", &(overlay->bpp))) {
+    return FALSE;
+  }
+
+  g_signal_emit (overlay, gst_cairo_overlay_signals[SIGNAL_CAPS_CHANGED], 0,
+      incaps, NULL);
+
+  return G_LIKELY (gst_video_format_parse_caps (incaps,
+          &overlay->caps_format, &overlay->caps_width, &overlay->caps_height));
+}
+
+static GstFlowReturn
+gst_cairo_overlay_transform_ip (GstBaseTransform * btrans, GstBuffer * buf)
+{
+
+  GstCairoOverlay *overlay = GST_CAIRO_OVERLAY (btrans);
+  cairo_surface_t *surface;
+  cairo_t *cr;
+  cairo_format_t format;
+
+  format = (overlay->bpp == 32) ? CAIRO_FORMAT_ARGB32 : CAIRO_FORMAT_RGB24;
+
+  surface =
+      cairo_image_surface_create_for_data (GST_BUFFER_DATA (buf), format,
+      overlay->caps_width, overlay->caps_height, overlay->caps_width * 4);
+  if (G_UNLIKELY (!surface))
+    return GST_FLOW_ERROR;
+
+  cr = cairo_create (surface);
+  if (G_UNLIKELY (!cr)) {
+    cairo_surface_destroy (surface);
+    return GST_FLOW_ERROR;
+  }
+
+  g_signal_emit (overlay, gst_cairo_overlay_signals[SIGNAL_DRAW], 0,
+      cr, GST_BUFFER_TIMESTAMP (buf), GST_BUFFER_DURATION (buf), NULL);
+
+  cairo_destroy (cr);
+  cairo_surface_destroy (surface);
+  return GST_FLOW_OK;
+}
+
+static void
+gst_cairo_overlay_base_init (gpointer g_class)
+{
+  GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
+
+  gst_element_class_set_details_simple (element_class, "Cairo overlay",
+      "Filter/Editor/Video",
+      "Render overlay on a video stream using Cairo",
+      "Jon Nordby <jononor@gmail.com>");
+
+  gst_element_class_add_pad_template (element_class,
+      gst_static_pad_template_get (&gst_cairo_overlay_sink_template));
+  gst_element_class_add_pad_template (element_class,
+      gst_static_pad_template_get (&gst_cairo_overlay_src_template));
+}
+
+static void
+gst_cairo_overlay_class_init (GstCairoOverlayClass * klass)
+{
+  GstBaseTransformClass *trans_class;
+
+  trans_class = (GstBaseTransformClass *) klass;
+
+  trans_class->set_caps = gst_cairo_overlay_set_caps;
+  trans_class->transform_ip = gst_cairo_overlay_transform_ip;
+
+  /**
+   * GstCairoOverlay::draw:
+   * @overlay: Overlay element emitting the signal.
+   * @cr: Cairo context to draw to.
+   * @timestamp: Timestamp (see GstClockTime) of the current buffer.
+   * @duration: Duration (see GstClockTime) of the current buffer.
+   * 
+   * This signal is emitted when the overlay should be drawn.
+   */
+  gst_cairo_overlay_signals[SIGNAL_DRAW] =
+      g_signal_new ("draw",
+      G_TYPE_FROM_CLASS (klass),
+      0,
+      0,
+      NULL,
+      NULL,
+      gst_cairo_marshal_VOID__BOXED_UINT64_UINT64,
+      G_TYPE_NONE, 3, CAIRO_GOBJECT_TYPE_CONTEXT, G_TYPE_UINT64, G_TYPE_UINT64);
+
+  /**
+   * GstCairoOverlay::caps-changed:
+   * @overlay: Overlay element emitting the signal.
+   * @caps: The caps of the element.
+   * 
+   * This signal is emitted when the caps of the element has changed.
+   */
+  gst_cairo_overlay_signals[SIGNAL_CAPS_CHANGED] =
+      g_signal_new ("caps-changed",
+      G_TYPE_FROM_CLASS (klass),
+      0,
+      0,
+      NULL, NULL, gst_cairo_marshal_VOID__BOXED, G_TYPE_NONE, 1, GST_TYPE_CAPS);
+}
+
+static void
+gst_cairo_overlay_init (GstCairoOverlay * overlay, GstCairoOverlayClass * klass)
+{
+}

ext/cairo/gstcairooverlay.h

@@ -0,0 +1,60 @@
+/* GStreamer
+ * Copyright (C) <2011> Jon Nordby <jononor@gmail.com>
+ *
+ * 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.
+ */
+
+#ifndef __GST_CAIRO_OVERLAY_H__
+#define __GST_CAIRO_OVERLAY_H__
+
+#include <gst/gst.h>
+#include <gst/video/video.h>
+#include <gst/video/gstvideofilter.h>
+
+#include <cairo.h>
+#include <cairo-gobject.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_CAIRO_OVERLAY \
+  (gst_cairo_overlay_get_type())
+#define GST_CAIRO_OVERLAY(obj) \
+  (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_CAIRO_OVERLAY,GstCairoOverlay))
+#define GST_CAIRO_OVERLAY_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_CAIRO_OVERLAY,GstCairoOverlayClass))
+#define GST_IS_CAIRO_OVERLAY(obj) \
+  (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_CAIRO_OVERLAY))
+#define GST_IS_CAIRO_OVERLAY_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_CAIRO_OVERLAY))
+
+typedef struct _GstCairoOverlay {
+  GstVideoFilter parent_instance;
+  /* < private > */
+  GstVideoFormat caps_format;
+  int caps_width;
+  int caps_height;
+  int bpp;
+} GstCairoOverlay;
+
+typedef struct _GstCairoOverlayClass {
+  GstVideoFilterClass parent_class;
+} GstCairoOverlayClass;
+
+GType gst_cairo_overlay_get_type(void);
+
+G_END_DECLS
+
+#endif /* __GST_CAIRO_OVERLAY_H__ */

tests/examples/Makefile.am

@@ -4,8 +4,16 @@ else
 JACK_DIR=
 endif
 
-SUBDIRS = audiofx equalizer $(JACK_DIR) level pulse rtp shapewipe spectrum v4l2
+if USE_CAIRO
+CAIRO_DIR=cairo
+else
+CAIRO_DIR=
+endif
 
-DIST_SUBDIRS = audiofx equalizer jack level pulse rtp shapewipe spectrum v4l2
+SUBDIRS = audiofx equalizer $(JACK_DIR) level pulse \
+	rtp shapewipe spectrum v4l2 $(CAIRO_DIR)
+
+DIST_SUBDIRS = audiofx equalizer jack level pulse \
+	rtp shapewipe spectrum v4l2 $(CAIRO_DIR)
 
 include $(top_srcdir)/common/parallel-subdirs.mak

tests/examples/cairo/.gitignore

@@ -0,0 +1 @@
+cairo_overlay

tests/examples/cairo/Makefile.am

@@ -0,0 +1,11 @@
+if USE_CAIRO_GOBJECT
+if HAVE_GTK
+noinst_PROGRAMS = cairo_overlay
+endif
+endif
+
+cairo_overlay_SOURCES = cairo_overlay.c
+cairo_overlay_CFLAGS = $(GST_CFLAGS) $(GTK_CFLAGS) $(CAIRO_CFLAGS)
+cairo_overlay_LDFLAGS = \
+	$(GST_LIBS) -lgstinterfaces-0.10 -lgstvideo-$(GST_MAJORMINOR) \
+	$(GTK_LIBS) $(CAIRO_LIBS)

tests/examples/cairo/cairo_overlay.c

@@ -0,0 +1,199 @@
+/* GStreamer
+ * Copyright (C) 2011 Jon Nordby <jononor@gmail.com>
+ *
+ * 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.
+ */
+
+/*
+ * Example showing usage of the cairooverlay element
+ * 
+ * Note: The example program not run on non-X11 platforms because
+ * it is using the xvimageoverlay element. That part of the code was
+ * roughly based on gst_x_overlay documentation.
+ */
+
+
+#include <gst/gst.h>
+#include <gst/video/video.h>
+#include <gst/interfaces/xoverlay.h>
+
+#include <gtk/gtk.h>
+#include <cairo.h>
+#include <cairo-gobject.h>
+
+#ifdef GDK_WINDOWING_X11
+#include <gdk/gdkx.h>
+#endif
+
+static gulong video_window_xid = 0;
+
+static GstBusSyncReply
+bus_sync_handler (GstBus * bus, GstMessage * message, gpointer user_data)
+{
+  if (GST_MESSAGE_TYPE (message) != GST_MESSAGE_ELEMENT)
+    return GST_BUS_PASS;
+  if (!gst_structure_has_name (message->structure, "prepare-xwindow-id"))
+    return GST_BUS_PASS;
+
+  if (video_window_xid != 0) {
+    GstXOverlay *xoverlay;
+
+    xoverlay = GST_X_OVERLAY (GST_MESSAGE_SRC (message));
+    gst_x_overlay_set_window_handle (xoverlay, video_window_xid);
+  } else {
+    g_warning ("Should have obtained video_window_xid by now!");
+  }
+
+  gst_message_unref (message);
+  return GST_BUS_DROP;
+}
+
+static void
+video_widget_realize_cb (GtkWidget * widget, gpointer data)
+{
+#ifdef GDK_WINDOWING_X11
+  video_window_xid = GDK_WINDOW_XID (widget->window);
+#endif
+}
+
+static GtkWidget *
+setup_gtk_window (void)
+{
+  GtkWidget *video_window;
+  GtkWidget *app_window;
+
+  app_window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+
+  video_window = gtk_drawing_area_new ();
+  g_signal_connect (video_window, "realize",
+      G_CALLBACK (video_widget_realize_cb), NULL);
+  gtk_widget_set_double_buffered (video_window, FALSE);
+
+  gtk_container_add (GTK_CONTAINER (app_window), video_window);
+  gtk_widget_show_all (app_window);
+
+  gtk_widget_realize (app_window);
+  g_assert (video_window_xid != 0);
+
+  return app_window;
+}
+
+/* Datastructure to share the state we are interested in between
+ * prepare and render function. */
+typedef struct
+{
+  gboolean valid;
+  int width;
+  int height;
+} CairoOverlayState;
+
+/* Store the information from the caps that we are interested in. */
+static void
+prepare_overlay (GstElement * overlay, GstCaps * caps, gpointer user_data)
+{
+  CairoOverlayState *state = (CairoOverlayState *) user_data;
+
+  gst_video_format_parse_caps (caps, NULL, &state->width, &state->height);
+  state->valid = TRUE;
+}
+
+/* Draw the overlay. 
+ * This function draws a cute "beating" heart. */
+static void
+draw_overlay (GstElement * overlay, cairo_t * cr, guint64 timestamp,
+    guint64 duration, gpointer user_data)
+{
+  CairoOverlayState *s = (CairoOverlayState *) user_data;
+  double scale;
+
+  if (!s->valid)
+    return;
+
+  scale = 2 * (((timestamp / (int) 1e7) % 70) + 30) / 100.0;
+  cairo_translate (cr, s->width / 2, (s->height / 2) - 30);
+  cairo_scale (cr, scale, scale);
+
+  cairo_move_to (cr, 0, 0);
+  cairo_curve_to (cr, 0, -30, -50, -30, -50, 0);
+  cairo_curve_to (cr, -50, 30, 0, 35, 0, 60);
+  cairo_curve_to (cr, 0, 35, 50, 30, 50, 0);
+  cairo_curve_to (cr, 50, -30, 0, -30, 0, 0);
+  cairo_set_source_rgba (cr, 0.9, 0.0, 0.1, 0.7);
+  cairo_fill (cr);
+}
+
+static GstElement *
+setup_gst_pipeline (CairoOverlayState * overlay_state)
+{
+  GstElement *pipeline;
+  GstElement *cairo_overlay;
+  GstElement *source, *adaptor1, *adaptor2, *sink;
+  GstBus *bus;
+
+  pipeline = gst_pipeline_new ("cairo-overlay-example");
+
+  /* Adaptors needed because cairooverlay only supports ARGB data */
+  source = gst_element_factory_make ("videotestsrc", "source");
+  adaptor1 = gst_element_factory_make ("ffmpegcolorspace", "adaptor1");
+  cairo_overlay = gst_element_factory_make ("cairooverlay", "overlay");
+  adaptor2 = gst_element_factory_make ("ffmpegcolorspace", "adaptor2");
+  sink = gst_element_factory_make ("xvimagesink", "sink");
+
+  /* If failing, the element could not be created */
+  g_assert (cairo_overlay);
+
+  /* Hook up the neccesary signals for cairooverlay */
+  g_signal_connect (cairo_overlay, "draw",
+      G_CALLBACK (draw_overlay), overlay_state);
+  g_signal_connect (cairo_overlay, "caps-changed",
+      G_CALLBACK (prepare_overlay), overlay_state);
+
+  gst_bin_add_many (GST_BIN (pipeline), source, adaptor1,
+      cairo_overlay, adaptor2, sink, NULL);
+
+  if (!gst_element_link_many (source, adaptor1,
+          cairo_overlay, adaptor2, sink, NULL)) {
+    g_warning ("Failed to link elements!");
+  }
+
+  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
+  gst_bus_set_sync_handler (bus, (GstBusSyncHandler) bus_sync_handler, NULL);
+  gst_object_unref (bus);
+
+  return pipeline;
+}
+
+int
+main (int argc, char **argv)
+{
+  GtkWidget *window;
+  GstElement *pipeline;
+  CairoOverlayState *overlay_state;
+
+  gtk_init (&argc, &argv);
+  gst_init (&argc, &argv);
+
+  window = setup_gtk_window ();
+  overlay_state = g_new (CairoOverlayState, 1);
+  pipeline = setup_gst_pipeline (overlay_state);
+
+  gst_element_set_state (pipeline, GST_STATE_PLAYING);
+  gtk_main ();
+
+  gst_object_unref (pipeline);
+  gtk_widget_destroy (GTK_WIDGET (window));
+  g_free (overlay_state);
+}