Add documentation for sections

3 files changed, 51 insertions, 2 deletions

diff --git a/docs/libs/gst-plugins-cairo-libs-sections.txt b/docs/libs/gst-plugins-cairo-libs-sections.txt
index 638f40b..2c83635 100644
--- a/docs/libs/gst-plugins-cairo-libs-sections.txt
+++ b/docs/libs/gst-plugins-cairo-libs-sections.txt
@@ -1,6 +1,5 @@
 <SECTION>
 <FILE>gstcairocaps</FILE>
-<TITLE>caps negotiation and format handling</TITLE>
 GstCairoFormatOption
 GstCairoFormat
 gst_cairo_caps_any
@@ -21,7 +20,6 @@ gst_cairo_format_equal
 
 <SECTION>
 <FILE>gstcairobuffer</FILE>
-<TITLE>buffers</TITLE>
 gst_cairo_buffer_new
 gst_cairo_buffer_new_similar
 gst_cairo_buffer_is_fixed
diff --git a/gst-libs/gst/cairo/gstcairobuffer.c b/gst-libs/gst/cairo/gstcairobuffer.c
index 3f12311..c13cc87 100644
--- a/gst-libs/gst/cairo/gstcairobuffer.c
+++ b/gst-libs/gst/cairo/gstcairobuffer.c
@@ -29,6 +29,36 @@
 #  include "gstcairoxbuffer.h"
 #endif
 
+/**
+ * SECTION:gstcairobuffer
+ * @title: Buffers
+ * @short_description: using video data
+ *
+ * This section describes how to modify buffers when using the GStreamer
+ * Cairo library.
+ *
+ * If at all possible, modifying buffers should be done using the Cairo
+ * library and without accessing the buffer data directly. This allows
+ * high performance and ensures portability of elements.
+ *
+ * Rendering is done by acquiring the #cairo_surface_t for all the buffers
+ * involved with gst_cairo_create_surface() and then using the Cairo API
+ * for modifications. Afterwards, all surfaces should be discarded. Do not
+ * keep a reference to surfaces. If you want to keep references, please
+ * keep the buffer around and use gst_cairo_create_surface() again later.
+ * 
+ * To create buffers for use in your element, use
+ * gst_cairo_pad_alloc_buffer(). This way, you'll automatically take
+ * advantage of hardware acceleration provided by the sink elements.
+ *
+ * If you are writing sink or source elements, the GStreamer Cairo library
+ * provides a way to create buffers using gst_cairo_buffer_new_similar() and
+ * surfaces using gst_cairo_create_similar_surface(). These functions are
+ * similar to cairo_surface_create_similar() in that they take extra steps
+ * to provide buffers or surfaces that are as compatible as possible with
+ * the provided surface and can take full advatange of hardware acceleration.
+ */
+
 G_DEFINE_TYPE (GstCairoBuffer, gst_cairo_buffer, GST_TYPE_BUFFER)
 
      static void gst_cairo_buffer_finalize (GstMiniObject * object)
diff --git a/gst-libs/gst/cairo/gstcairocaps.c b/gst-libs/gst/cairo/gstcairocaps.c
index 9836c5f..433e2ca 100644
--- a/gst-libs/gst/cairo/gstcairocaps.c
+++ b/gst-libs/gst/cairo/gstcairocaps.c
@@ -29,6 +29,27 @@
 #include "gstcairocapsany.h"
 
 /**
+ * SECTION:gstcairocaps
+ * @title: Caps
+ * @short_description: caps negotiation and format handling
+ *
+ * This section describes how to handle #GstCaps inside an element that
+ * uses this library.
+ *
+ * Fixed caps as passed to a setcaps function are converted into a
+ * #GstCairoFormat using gst_cairo_format_new(), which is a simple and
+ * fast wrapper around a static caps. It is suggested that you do not store
+ * things like framerate, width or height, but use a #GstCairoFormat instead.
+ * These formats are also required when converting a #GstBuffer into a
+ * #cairo_surface_t.
+ *
+ * The GStreamer Cairo library also provides some utility function that 
+ * help during caps negotiation. Those are listed here, too. The most 
+ * important one certainly is gst_cairo_caps_expand() that eases caps
+ * transformations.
+ */
+
+/**
  * gst_cairo_caps_any:
  *
  * Returns a #GstCaps that references all formats that can be handled by