video: Abstract surface API for HW accelerated codecs

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

@@ -39,6 +39,9 @@
       <xi:include href="xml/gstbasevideodecoder.xml" />
       <xi:include href="xml/gstbasevideoencoder.xml" />
       <xi:include href="xml/gstbasevideoutils.xml" />
+      <xi:include href="xml/gstvideocontext.xml" />
+      <xi:include href="xml/gstsurfacebuffer.xml" />
+      <xi:include href="xml/gstsurfaceconverter.xml" />
     </chapter>
   </part>
 

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

@@ -404,3 +404,22 @@ gst_base_video_rawvideo_convert
 gst_base_video_encoded_video_convert
 gst_video_state_get_timestamp
 </SECTION>
+
+<SECTION>
+<FILE>gstsurfacebuffer</FILE>
+<TITLE>GstSurfaceBuffer</TITLE>
+GST_VIDEO_CAPS_SURFACE
+GstSurfaceBuffer
+GstSurfaceBufferClass
+gst_surface_buffer_get_type
+gst_surface_buffer_create_converter
+</SECTION>
+
+<SECTION>
+<FILE>gstsurfaceconverter</FILE>
+<TITLE>GstSurfaceConverter</TITLE>
+GstSurfaceConverter
+GstSurfaceConverterInterface
+gst_surface_converter_get_type
+gst_surface_converter_upload
+</SECTION>

gst-libs/gst/video/Makefile.am

@@ -7,14 +7,20 @@ libgstbasevideo_@GST_MAJORMINOR@_la_SOURCES = \
 	gstbasevideocodec.c \
 	gstbasevideoutils.c \
 	gstbasevideodecoder.c \
-	gstbasevideoencoder.c
+	gstbasevideoencoder.c \
+	gstsurfacebuffer.c \
+	gstsurfaceconverter.c \
+	videocontext.c
 
 libgstbasevideo_@GST_MAJORMINOR@includedir = $(includedir)/gstreamer-@GST_MAJORMINOR@/gst/video
 libgstbasevideo_@GST_MAJORMINOR@include_HEADERS = \
 	gstbasevideocodec.h \
 	gstbasevideoutils.h \
 	gstbasevideodecoder.h \
-	gstbasevideoencoder.h
+	gstbasevideoencoder.h \
+	gstsurfacebuffer.h \
+	gstsurfaceconverter.h \
+	videocontext.h
 
 libgstbasevideo_@GST_MAJORMINOR@_la_CFLAGS = \
 	$(GST_PLUGINS_BAD_CFLAGS) \

gst-libs/gst/video/gstsurfacebuffer.c

@@ -0,0 +1,88 @@
+/* GStreamer
+ * Copyright (C) 2011 Collabora Ltd.
+ * Copyright (C) 2011 Intel
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.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.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "gstsurfacebuffer.h"
+
+/**
+ * SECTION:gstsurfacebuffer
+ * @short_description: Accelerated surface base class
+ *
+ * This base class is used to abstract hardware accelerated buffers and enable
+ * generic convertion to standard type such as GL textures. The media type for
+ * those buffers is defined by #GST_VIDEO_CAPS_SURFACE. An implementation
+ * specific type must be set using the "type" key (e.g. type="vaapi").
+ * Available convertion type are speficied using seperate boolean
+ * arguement (e.g. opengl=true). Having this information in the capabilities
+ * allow easy negotiating of such feature with other elements (e.g. a
+ * ClutterGstVideoSink can claim accpeting caps "video/x-surface,opengl=true").
+ * <note>
+ *   The GstVideoContext interface is unstable API and may change in future.
+ *   One can define GST_USE_UNSTABLE_API to acknowledge and avoid this warning.
+ * </note>
+ */
+
+G_DEFINE_TYPE (GstSurfaceBuffer, gst_surface_buffer, GST_TYPE_BUFFER);
+
+static GstSurfaceConverter *
+gst_surface_buffer_default_create_converter (GstSurfaceBuffer * surface,
+    const gchar * type, GValue * dest)
+{
+  return NULL;
+}
+
+static void
+gst_surface_buffer_class_init (GstSurfaceBufferClass * klass)
+{
+  klass->create_converter = gst_surface_buffer_default_create_converter;
+}
+
+static void
+gst_surface_buffer_init (GstSurfaceBuffer * surface)
+{
+  /* Nothing to do */
+}
+
+/**
+ * gst_surface_buffer_create_converter:
+ * @buffer: a #GstSurfaceBuffer
+ * @type: the type to convert to
+ * @dest: a #GValue containing the destination to upload
+ *
+ * This method is used to create a type specific converter. The converter will
+ * serve as context to accelerate the data convertion. This converter object
+ * shall be discarded when the pipeline state changes to NULL and renewed when
+ * caps are changed.
+ *
+ * Returns: newly allocated #GstSurfaceConverter
+ */
+GstSurfaceConverter *
+gst_surface_buffer_create_converter (GstSurfaceBuffer * buffer,
+    const gchar * type, GValue * dest)
+{
+  g_return_val_if_fail (GST_IS_SURFACE_BUFFER (buffer), FALSE);
+  return GST_SURFACE_BUFFER_GET_CLASS (buffer)->create_converter (buffer,
+      type, dest);
+}

gst-libs/gst/video/gstsurfacebuffer.h

@@ -0,0 +1,94 @@
+/* GStreamer
+ * Copyright (C) 2011 Collabora Ltd.
+ * Copyright (C) 2011 Intel
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.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_SURFACE_BUFFER_H_
+#define _GST_SURFACE_BUFFER_H_
+
+#ifndef GST_USE_UNSTABLE_API
+#warning "GstSurfaceBuffer is unstable API and may change in future."
+#warning "You can define GST_USE_UNSTABLE_API to avoid this warning."
+#endif
+
+#include <gst/gst.h>
+#include <gst/video/gstsurfaceconverter.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_SURFACE_BUFFER                       (gst_surface_buffer_get_type())
+#define GST_SURFACE_BUFFER(obj)                       (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_SURFACE_BUFFER,GstSurfaceBuffer))
+#define GST_SURFACE_BUFFER_CLASS(klass)               (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_SURFACE_BUFFER,GstSurfaceBufferClass))
+#define GST_SURFACE_BUFFER_GET_CLASS(obj)             (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_SURFACE_BUFFER,GstSurfaceBufferClass))
+#define GST_IS_SURFACE_BUFFER(obj)                    (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_SURFACE_BUFFER))
+#define GST_IS_SURFACE_BUFFER_CLASS(obj)              (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_SURFACE_BUFFER))
+
+/**
+ * GST_VIDEO_CAPS_SURFACE:
+ *
+ * Base caps for GstSurfaceBuffer. Implementation specific type must be marked
+ * using the type attribute (e.g. type=vaapi). Available convertion shall be
+ * specified using boolean attributes (e.g. opengl=true).
+ */
+#define GST_VIDEO_CAPS_SURFACE "video/x-surface"
+
+typedef struct _GstSurfaceBuffer GstSurfaceBuffer;
+typedef struct _GstSurfaceBufferClass GstSurfaceBufferClass;
+
+/**
+ * GstSurfaceBuffer:
+ * @parent: parent object
+ */
+struct _GstSurfaceBuffer
+{
+  GstBuffer parent;
+
+  /*< private >*/
+  void *padding[GST_PADDING];
+};
+
+/**
+ * GstSurfaceBufferClass:
+ * @parent_class: parent class type.
+ * @create_converter: vmethod to create a converter.
+ *
+ * #GstVideoContextInterface interface.
+ */
+struct _GstSurfaceBufferClass
+{
+  GstBufferClass parent_class;
+
+  GstSurfaceConverter * (*create_converter) (GstSurfaceBuffer *buffer,
+                                             const gchar *type,
+                                             GValue *dest);
+
+  /*< private >*/
+  void *padding[GST_PADDING];
+};
+
+GType                       gst_surface_buffer_get_type         (void);
+
+GstSurfaceConverter  *gst_surface_buffer_create_converter (GstSurfaceBuffer *buffer,
+                                                           const gchar *type,
+                                                           GValue *dest);
+
+G_END_DECLS
+
+#endif

gst-libs/gst/video/gstsurfaceconverter.c

@@ -0,0 +1,80 @@
+/* GStreamer
+ * Copyright (C) 2011 Collabora Ltd.
+ * Copyright (C) 2011 Intel
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.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.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include "gstsurfaceconverter.h"
+#include "gstsurfacebuffer.h"
+
+/**
+ * SECTION:gstsurfaceconverter
+ * @short_description: Interface for #GstSurfaceBuffer convertion
+ *
+ * Objects implementing this interface are used as a convertion context. This
+ * allow element optimizing the upload by keeping required resources between
+ * uploads. The context must be discarded when the pipeline goes to
+ * #GST_STATE_NULL or renewed whenever the caps are changed.
+ * <note>
+ *   The GstVideoContext interface is unstable API and may change in future.
+ *   One can define GST_USE_UNSTABLE_API to acknowledge and avoid this warning.
+ * </note>
+ *
+ * <refsect2>
+ * <title>Example uploading to GL texture</title>
+ * |[
+ * if (G_UNLIKELY (priv->converter == NULL))
+ *   priv->converter = gst_surface_buffer_create_converter (surface, "opengl", &value);
+ *
+ * gst_surface_converter_uplaod (priv->converter, surface);
+ * ]|
+ * </refsect2>
+ */
+
+G_DEFINE_INTERFACE (GstSurfaceConverter, gst_surface_converter, G_TYPE_INVALID);
+
+static void
+gst_surface_converter_default_init (GstSurfaceConverterInterface * iface)
+{
+  /* default virtual functions */
+  iface->upload = NULL;
+}
+
+/**
+ * gst_surface_converter_upload:
+ * @converter: a #GstSurfaceConverter
+ * @buffer: the #GstSurfaceBuffer to upload
+ *
+ * Convert and uploads the #GstSurfaceBuffer to the converter destination.
+ *
+ * Returns: #TRUE on success, #FALSE otherwise
+ */
+gboolean
+gst_surface_converter_upload (GstSurfaceConverter * converter,
+    GstSurfaceBuffer * buffer)
+{
+  g_return_val_if_fail (GST_IS_SURFACE_CONVERTER (converter), FALSE);
+  g_return_val_if_fail (GST_IS_SURFACE_BUFFER (buffer), FALSE);
+  return GST_SURFACE_CONVERTER_GET_IFACE (converter)->upload (converter,
+      buffer);
+}

gst-libs/gst/video/gstsurfaceconverter.h

@@ -0,0 +1,66 @@
+/* GStreamer
+ * Copyright (C) 2011 Collabora Ltd.
+ * Copyright (C) 2011 Intel
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.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_SURFACE_CONVERTER_H_
+#define _GST_SURFACE_CONVERTER_H_
+
+#ifndef GST_USE_UNSTABLE_API
+#warning "GstSurfaceConverter is unstable API and may change in future."
+#warning "You can define GST_USE_UNSTABLE_API to avoid this warning."
+#endif
+
+#include <gst/gst.h>
+
+G_BEGIN_DECLS
+
+#define GST_TYPE_SURFACE_CONVERTER             (gst_surface_converter_get_type ())
+#define GST_SURFACE_CONVERTER(obj)             (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_SURFACE_CONVERTER, GstSurfaceConverter))
+#define GST_IS_SURFACE_CONVERTER(obj)          (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_SURFACE_CONVERTER))
+#define GST_SURFACE_CONVERTER_GET_IFACE(inst)  (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GST_TYPE_SURFACE_CONVERTER, GstSurfaceConverterInterface))
+
+typedef struct _GstSurfaceBuffer GstSurfaceBuffer;
+typedef struct _GstSurfaceConverter GstSurfaceConverter;
+typedef struct _GstSurfaceConverterInterface GstSurfaceConverterInterface;
+
+/**
+ * GstSurfaceConverterInterface:
+ * @parent: parent interface type.
+ * @upload: vmethod to upload #GstSurfaceBuffer.
+ *
+ * #GstSurfaceConverterInterface interface.
+ */
+struct _GstSurfaceConverterInterface
+{
+  GTypeInterface parent;
+
+  gboolean (*upload) (GstSurfaceConverter *converter,
+                      GstSurfaceBuffer *buffer);
+};
+
+GType     gst_surface_converter_get_type (void);
+
+gboolean  gst_surface_converter_upload (GstSurfaceConverter *converter,
+                                        GstSurfaceBuffer *buffer);
+
+G_END_DECLS
+
+#endif