Document public API for libgstvaapi-*.so.*.

10 files changed, 441 insertions, 1 deletions

diff --git a/Makefile.am b/Makefile.am
index 99d568d1..8fe73ad7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 AUTOMAKE_OPTIONS = foreign
 
-SUBDIRS = debian gst-libs pkgconfig sys tests
+SUBDIRS = debian gst-libs pkgconfig sys tests docs
 
 # Extra clean files so that maintainer-clean removes *everything*
 MAINTAINERCLEANFILES = \
diff --git a/NEWS b/NEWS
index 4243881d..f17b1ca5 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,7 @@ gst-vaapi NEWS -- summary of changes.  2010-03-DD
 Copyright (C) 2010 Splitted-Desktop Systems
 
 Version 0.1.1 - DD.Mar.2010
+* Document public API for libgstvaapi-*.so.*
 * Optimize `vaapiconvert' pipeline (direct-rendering)
 
 Version 0.1.0 - 16.Mar.2010
diff --git a/configure.ac b/configure.ac
index c93f844f..f8f843d7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -88,6 +88,10 @@ AC_PROG_CC
 AM_PROG_CC_C_O
 AC_PROG_LIBTOOL
 
+dnl Check for Gtk doc
+GTK_DOC_CHECK([1.9])
+AM_CONDITIONAL([BUILD_GTK_DOC], [test "x$enable_gtk_doc" = "xyes"])
+
 dnl Check for GLib
 PKG_CHECK_MODULES([GLIB], [glib-2.0])
 AC_SUBST(GLIB_CFLAGS)
@@ -186,6 +190,10 @@ debian/libgstvaapi.install.in
 debian/libgstvaapi-dev.install.in
     debian/libgstvaapi-x11-$GST_VAAPI_MAJOR_VERSION.install:\
 debian/libgstvaapi-x11.install.in
+    docs/Makefile
+    docs/reference/Makefile
+    docs/reference/libs/Makefile
+    docs/reference/libs/libs-docs.xml
     gst-libs/Makefile
     gst-libs/gst/Makefile
     gst-libs/gst/vaapi/Makefile
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 00000000..516af700
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,10 @@
+SUBDIRS =
+
+if BUILD_GTK_DOC
+SUBDIRS += reference
+endif
+
+DIST_SUBDIRS = reference
+
+# Extra clean files so that maintainer-clean removes *everything*
+MAINTAINERCLEANFILES = Makefile.in
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 00000000..d29d4576
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,4 @@
+SUBDIRS = libs
+
+# Extra clean files so that maintainer-clean removes *everything*
+MAINTAINERCLEANFILES = Makefile.in
diff --git a/docs/reference/libs/Makefile.am b/docs/reference/libs/Makefile.am
new file mode 100644
index 00000000..8d1a0fcd
--- /dev/null
+++ b/docs/reference/libs/Makefile.am
@@ -0,0 +1,105 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE = libs
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR = $(top_srcdir)/gst-libs/gst/vaapi
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS = --type-init-func="g_type_init()"
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS = --deprecated-guards="GST_VAAPI_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS = --sgml-mode --output-format=xml --name-space=$(DOC_MODULE)
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS =
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS = \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject \
+	--extra-dir=$(CAIRO_PREFIX)/share/gtk-doc/html/cairo \
+	--extra-dir=$(PANGO_PREFIX)/share/gtk-doc/html/pango
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB = $(top_srcdir)/gst-libs/gst/vaapi/*.h
+CFILE_GLOB = $(top_srcdir)/gst-libs/gst/vaapi/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES = \
+	gstvaapidebug.h \
+	gstvaapiutils.h \
+	gstvaapiutils_x11.h \
+	$(NULL)
+
+EXTRA_HFILES = \
+	$(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES = \
+	$(NULL)
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files = \
+	$(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files = \
+	$(NULL)
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+
+INCLUDES = \
+	-I$(top_srcdir) \
+	-I$(top_srcdir)/gst-libs \
+	-I$(top_srcdir)/gst-libs/gst/vaapi \
+	$(GLIB_CFLAGS)
+
+GTKDOC_LIBS = \
+	$(top_builddir)/gst-libs/gst/vaapi/libgstvaapi-$(GST_MAJORMINOR).la \
+	$(top_builddir)/gst-libs/gst/vaapi/libgstvaapi-x11-$(GST_MAJORMINOR).la \
+	$(GLIB_LIBS)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += \
+	$(NULL)
+
+# Extra clean files so that maintainer-clean removes *everything*
+MAINTAINERCLEANFILES = Makefile.in lib-docs.xml
diff --git a/docs/reference/libs/libs-docs.xml.in b/docs/reference/libs/libs-docs.xml.in
new file mode 100644
index 00000000..c9683aca
--- /dev/null
+++ b/docs/reference/libs/libs-docs.xml.in
@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>GStreamer VA-API Plugins @GST_MAJORMINOR@ Library Reference Manual</title>
+    <releaseinfo>
+      for GStreamer VA-API Library @GST_MAJORMINOR@ (@PACKAGE_VERSION@)
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>GStreamer VA-API Plugins Library</title>
+    <xi:include href="xml/gstvaapidisplay.xml"/>
+    <xi:include href="xml/gstvaapidisplay_x11.xml"/>
+    <xi:include href="xml/gstvaapiwindow.xml"/>
+    <xi:include href="xml/gstvaapiwindow_x11.xml"/>
+    <xi:include href="xml/gstvaapisurface.xml"/>
+    <xi:include href="xml/gstvaapiimage.xml"/>
+    <xi:include href="xml/gstvaapiimageformat.xml"/>
+    <xi:include href="xml/gstvaapisubpicture.xml"/>
+    <xi:include href="xml/gstvaapivideopool.xml"/>
+    <xi:include href="xml/gstvaapisurfacepool.xml"/>
+    <xi:include href="xml/gstvaapiimagepool.xml"/>
+    <xi:include href="xml/gstvaapivideobuffer.xml"/>
+    <xi:include href="xml/gstvaapivideosink.xml"/>
+  </chapter>
+</book>
diff --git a/docs/reference/libs/libs-overrides.txt b/docs/reference/libs/libs-overrides.txt
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/reference/libs/libs-overrides.txt
diff --git a/docs/reference/libs/libs-sections.txt b/docs/reference/libs/libs-sections.txt
new file mode 100644
index 00000000..c919a70f
--- /dev/null
+++ b/docs/reference/libs/libs-sections.txt
@@ -0,0 +1,272 @@
+<SECTION>
+<FILE>gstvaapisurfacepool</FILE>
+<TITLE>GstVaapiSurfacePool</TITLE>
+GstVaapiSurfacePool
+GstVaapiSurfacePoolClass
+gst_vaapi_surface_pool_new
+<SUBSECTION Standard>
+GST_VAAPI_SURFACE_POOL
+GST_VAAPI_IS_SURFACE_POOL
+GST_VAAPI_TYPE_SURFACE_POOL
+gst_vaapi_surface_pool_get_type
+GST_VAAPI_SURFACE_POOL_CLASS
+GST_VAAPI_IS_SURFACE_POOL_CLASS
+GST_VAAPI_SURFACE_POOL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapivideopool</FILE>
+<TITLE>GstVaapiVideoPool</TITLE>
+GstVaapiVideoPool
+GstVaapiVideoPoolClass
+gst_vaapi_video_pool_get_caps
+gst_vaapi_video_pool_get_object
+gst_vaapi_video_pool_put_object
+<SUBSECTION Standard>
+GST_VAAPI_VIDEO_POOL
+GST_VAAPI_IS_VIDEO_POOL
+GST_VAAPI_TYPE_VIDEO_POOL
+gst_vaapi_video_pool_get_type
+GST_VAAPI_VIDEO_POOL_CLASS
+GST_VAAPI_IS_VIDEO_POOL_CLASS
+GST_VAAPI_VIDEO_POOL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapivideosink</FILE>
+<TITLE>GstVaapiVideoSink</TITLE>
+GST_VAAPI_VIDEO_SINK_GET_INTERFACE
+GstVaapiVideoSinkInterface
+gst_vaapi_video_sink_get_display
+gst_vaapi_video_sink_lookup
+<SUBSECTION Standard>
+GST_VAAPI_VIDEO_SINK
+GST_VAAPI_IS_VIDEO_SINK
+GST_VAAPI_TYPE_VIDEO_SINK
+gst_vaapi_video_sink_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapidisplay_x11</FILE>
+GST_VAAPI_DISPLAY_XDISPLAY
+<TITLE>GstVaapiDisplayX11</TITLE>
+GstVaapiDisplayX11
+GstVaapiDisplayX11Class
+gst_vaapi_display_x11_new
+gst_vaapi_display_x11_new_with_display
+gst_vaapi_display_x11_get_display
+<SUBSECTION Standard>
+GST_VAAPI_DISPLAY_X11
+GST_VAAPI_IS_DISPLAY_X11
+GST_VAAPI_TYPE_DISPLAY_X11
+gst_vaapi_display_x11_get_type
+GST_VAAPI_DISPLAY_X11_CLASS
+GST_VAAPI_IS_DISPLAY_X11_CLASS
+GST_VAAPI_DISPLAY_X11_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapiwindow_x11</FILE>
+<TITLE>GstVaapiWindowX11</TITLE>
+GstVaapiWindowX11
+GstVaapiWindowX11Class
+gst_vaapi_window_x11_new
+gst_vaapi_window_x11_new_with_xid
+gst_vaapi_window_x11_get_xid
+<SUBSECTION Standard>
+GST_VAAPI_WINDOW_X11
+GST_VAAPI_IS_WINDOW_X11
+GST_VAAPI_TYPE_WINDOW_X11
+gst_vaapi_window_x11_get_type
+GST_VAAPI_WINDOW_X11_CLASS
+GST_VAAPI_IS_WINDOW_X11_CLASS
+GST_VAAPI_WINDOW_X11_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapidisplay</FILE>
+GST_VAAPI_DISPLAY_VADISPLAY
+GST_VAAPI_DISPLAY_LOCK
+GST_VAAPI_DISPLAY_UNLOCK
+<TITLE>GstVaapiDisplay</TITLE>
+GstVaapiDisplay
+GstVaapiDisplayClass
+gst_vaapi_display_new_with_display
+gst_vaapi_display_lock
+gst_vaapi_display_unlock
+gst_vaapi_display_get_display
+gst_vaapi_display_has_profile
+gst_vaapi_display_get_image_caps
+gst_vaapi_display_has_image_format
+gst_vaapi_display_get_subpicture_caps
+gst_vaapi_display_has_subpicture_format
+<SUBSECTION Standard>
+GST_VAAPI_DISPLAY
+GST_VAAPI_IS_DISPLAY
+GST_VAAPI_TYPE_DISPLAY
+gst_vaapi_display_get_type
+GST_VAAPI_DISPLAY_CLASS
+GST_VAAPI_IS_DISPLAY_CLASS
+GST_VAAPI_DISPLAY_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapiimagepool</FILE>
+<TITLE>GstVaapiImagePool</TITLE>
+GstVaapiImagePool
+GstVaapiImagePoolClass
+gst_vaapi_image_pool_new
+<SUBSECTION Standard>
+GST_VAAPI_IMAGE_POOL
+GST_VAAPI_IS_IMAGE_POOL
+GST_VAAPI_TYPE_IMAGE_POOL
+gst_vaapi_image_pool_get_type
+GST_VAAPI_IMAGE_POOL_CLASS
+GST_VAAPI_IS_IMAGE_POOL_CLASS
+GST_VAAPI_IMAGE_POOL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapivideobuffer</FILE>
+<TITLE>GstVaapiVideoBuffer</TITLE>
+GstVaapiVideoBuffer
+GstVaapiVideoBufferClass
+gst_vaapi_video_buffer_new_from_pool
+gst_vaapi_video_buffer_new_with_image
+gst_vaapi_video_buffer_new_with_surface
+gst_vaapi_video_buffer_get_image
+gst_vaapi_video_buffer_set_image
+gst_vaapi_video_buffer_set_image_from_pool
+gst_vaapi_video_buffer_get_surface
+gst_vaapi_video_buffer_set_surface
+gst_vaapi_video_buffer_set_surface_from_pool
+<SUBSECTION Standard>
+GST_VAAPI_VIDEO_BUFFER
+GST_VAAPI_IS_VIDEO_BUFFER
+GST_VAAPI_TYPE_VIDEO_BUFFER
+gst_vaapi_video_buffer_get_type
+GST_VAAPI_VIDEO_BUFFER_CLASS
+GST_VAAPI_IS_VIDEO_BUFFER_CLASS
+GST_VAAPI_VIDEO_BUFFER_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapiwindow</FILE>
+<TITLE>GstVaapiWindow</TITLE>
+GstVaapiWindow
+GstVaapiWindowClass
+gst_vaapi_window_show
+gst_vaapi_window_hide
+gst_vaapi_window_get_width
+gst_vaapi_window_get_height
+gst_vaapi_window_get_size
+gst_vaapi_window_set_width
+gst_vaapi_window_set_height
+gst_vaapi_window_set_size
+gst_vaapi_window_put_surface
+gst_vaapi_window_put_surface_full
+<SUBSECTION Standard>
+GST_VAAPI_WINDOW
+GST_VAAPI_IS_WINDOW
+GST_VAAPI_TYPE_WINDOW
+gst_vaapi_window_get_type
+GST_VAAPI_WINDOW_CLASS
+GST_VAAPI_IS_WINDOW_CLASS
+GST_VAAPI_WINDOW_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapiimage</FILE>
+GST_VAAPI_IMAGE_FORMAT
+GST_VAAPI_IMAGE_WIDTH
+GST_VAAPI_IMAGE_HEIGHT
+<TITLE>GstVaapiImage</TITLE>
+GstVaapiImage
+GstVaapiImageClass
+gst_vaapi_image_new
+gst_vaapi_image_new_with_image
+gst_vaapi_image_get_id
+gst_vaapi_image_get_image
+gst_vaapi_image_get_display
+gst_vaapi_image_get_format
+gst_vaapi_image_get_width
+gst_vaapi_image_get_height
+gst_vaapi_image_get_size
+gst_vaapi_image_is_linear
+gst_vaapi_image_is_mapped
+gst_vaapi_image_map
+gst_vaapi_image_unmap
+gst_vaapi_image_get_plane_count
+gst_vaapi_image_get_plane
+gst_vaapi_image_get_pitch
+gst_vaapi_image_get_data_size
+gst_vaapi_image_update_from_buffer
+<SUBSECTION Standard>
+GST_VAAPI_IMAGE
+GST_VAAPI_IS_IMAGE
+GST_VAAPI_TYPE_IMAGE
+gst_vaapi_image_get_type
+GST_VAAPI_IMAGE_CLASS
+GST_VAAPI_IS_IMAGE_CLASS
+GST_VAAPI_IMAGE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapisurface</FILE>
+GstVaapiChromaType
+<TITLE>GstVaapiSurface</TITLE>
+GstVaapiSurface
+GstVaapiSurfaceClass
+gst_vaapi_surface_new
+gst_vaapi_surface_get_id
+gst_vaapi_surface_get_display
+gst_vaapi_surface_get_chroma_type
+gst_vaapi_surface_get_width
+gst_vaapi_surface_get_height
+gst_vaapi_surface_get_size
+gst_vaapi_surface_derive_image
+gst_vaapi_surface_get_image
+gst_vaapi_surface_put_image
+gst_vaapi_surface_sync
+<SUBSECTION Standard>
+GST_VAAPI_SURFACE
+GST_VAAPI_IS_SURFACE
+GST_VAAPI_TYPE_SURFACE
+gst_vaapi_surface_get_type
+GST_VAAPI_SURFACE_CLASS
+GST_VAAPI_IS_SURFACE_CLASS
+GST_VAAPI_SURFACE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapisubpicture</FILE>
+<TITLE>GstVaapiSubpicture</TITLE>
+GstVaapiSubpicture
+GstVaapiSubpictureClass
+gst_vaapi_subpicture_new
+gst_vaapi_subpicture_get_id
+gst_vaapi_subpicture_get_image
+gst_vaapi_subpicture_set_image
+<SUBSECTION Standard>
+GST_VAAPI_SUBPICTURE
+GST_VAAPI_IS_SUBPICTURE
+GST_VAAPI_TYPE_SUBPICTURE
+gst_vaapi_subpicture_get_type
+GST_VAAPI_SUBPICTURE_CLASS
+GST_VAAPI_IS_SUBPICTURE_CLASS
+GST_VAAPI_SUBPICTURE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>gstvaapiimageformat</FILE>
+<TITLE>GstVaapiImageFormat</TITLE>
+GstVaapiImageFormat
+gst_vaapi_image_format_is_rgb
+gst_vaapi_image_format_is_yuv
+gst_vaapi_image_format
+gst_vaapi_image_format_from_caps
+gst_vaapi_image_format_from_fourcc
+gst_vaapi_image_format_get_va_format
+gst_vaapi_image_format_get_caps
+gst_vaapi_image_format_get_score
+</SECTION>
diff --git a/docs/reference/libs/libs.types b/docs/reference/libs/libs.types
new file mode 100644
index 00000000..3efeb0a7
--- /dev/null
+++ b/docs/reference/libs/libs.types
@@ -0,0 +1,12 @@
+gst_vaapi_surface_pool_get_type
+gst_vaapi_video_pool_get_type
+gst_vaapi_video_sink_get_type
+gst_vaapi_display_x11_get_type
+gst_vaapi_window_x11_get_type
+gst_vaapi_display_get_type
+gst_vaapi_image_pool_get_type
+gst_vaapi_video_buffer_get_type
+gst_vaapi_window_get_type
+gst_vaapi_image_get_type
+gst_vaapi_surface_get_type
+gst_vaapi_subpicture_get_type