start to write the gtk doc

14 files changed, 280 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 6d03e45..623bc95 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2008-09-29  Julien Isorce  <julien.isorce@gmail.com>
+
+	* docs/DEBUGGING
+	* gst/gl/gltestsrc.c
+	* gst/gl/gstglbumper.c
+	* gst/gl/gstglcolorscale.c
+	* gst/gl/gstgldownload.c
+	* gst/gl/gstglfilterapp.c
+	* gst/gl/gstglfiltercube.c
+	* gst/gl/gstglfilterglass.c
+	* gst/gl/gstglimagesink.c
+	* gst/gl/gstgltestsrc.c
+	* gst/gl/gstglupload.c
+	* gst/gl/gstopengl.c
+	Fix gltestsrc (SMPTE was a little bit dark) and start to write the gtk doc (no tested)
+
 2008-09-25  Julien Isorce  <julien.isorce@gmail.com>
 
 	* gst/gl/gstglfilterglass.c:
diff --git a/TODO b/TODO
index f636032..9262a05 100644
--- a/TODO
+++ b/TODO
@@ -102,4 +102,4 @@
 	  -> it seems we cannot remove this glsl ATI compiler message.
 	  
     
-- 22: move gst-plugins-gl/docs/libgstopengl.pdf to Gdoc
+(ALMOST DONE) - 22: write gtk-doc
diff --git a/docs/DEBUGGING b/docs/DEBUGGING
index bc72d1c..b304341 100644
--- a/docs/DEBUGGING
+++ b/docs/DEBUGGING
@@ -45,8 +45,8 @@ export GST_GL_SHADER_DEBUG=1
 gst-launch-0.10 videotestsrc ! glimagesink
 when you are done, just type "export -n GST_GL_SHADER_DEBUG" to unset it.
 
-or just prepend your app with GST_GL_SHADER=1 (no need to unset):
-GST_GL_SHADER=1 gst-launch-0.10 videotestsrc ! glimagesink
+or just prepend your app with GST_GL_SHADER_DEBUG=1 (no need to unset):
+GST_GL_SHADER_DEBUG=1 gst-launch-0.10 videotestsrc ! glimagesink
 Note: the "1" value is completely arbitrary, what matters here is whether the
 environment variable is set or not.
 
diff --git a/gst/gl/gltestsrc.c b/gst/gl/gltestsrc.c
index a3a550f..4b5f9f0 100644
--- a/gst/gl/gltestsrc.c
+++ b/gst/gl/gltestsrc.c
@@ -96,9 +96,6 @@ gst_gl_test_src_smpte (GstGLTestSrc * v, GstGLBuffer * buffer, int w, int h)
   glMatrixMode (GL_PROJECTION);
   glLoadIdentity ();
 
-  glMatrixMode (GL_MODELVIEW);
-  glLoadIdentity ();
-
   for (i = 0; i < 7; i++) {
     glColor4f (vts_colors[i].R * (1 / 255.0f), vts_colors[i].G * (1 / 255.0f),
         vts_colors[i].B * (1 / 255.0f), 1.0f);
@@ -173,7 +170,7 @@ gst_gl_test_src_smpte (GstGLTestSrc * v, GstGLBuffer * buffer, int w, int h)
     glEnd ();
   }
 
-  glColor4f (0.5, 0.5, 0.5, 1.0);
+  glColor4f (1.0, 1.0, 1.0, 1.0);
   glBegin (GL_QUADS);
   glVertex3f (-1.0 + 2.0 * (0.75), -1.0 + 2.0 * 1, 0);
   glVertex3f (-1.0 + 2.0 * (1.0), -1.0 + 2.0 * 1, 0);
diff --git a/gst/gl/gstglbumper.c b/gst/gl/gstglbumper.c
index 38cd10e..61fd4f4 100644
--- a/gst/gl/gstglbumper.c
+++ b/gst/gl/gstglbumper.c
@@ -19,6 +19,20 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glbumper
+ *
+ * Bump mapping using the normal method.
+ *
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! glbumper location=normalmap.bmp ! glimagesink
+ * ]| A pipeline to test normal mapping.
+ * FBO and GLSL are required.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstglcolorscale.c b/gst/gl/gstglcolorscale.c
index dae92af..9812a38 100644
--- a/gst/gl/gstglcolorscale.c
+++ b/gst/gl/gstglcolorscale.c
@@ -18,6 +18,30 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glcolorscale
+ *
+ * video frame scaling and colorspace conversion.
+ *
+ * <refsect2>
+ * <title>Scaling and Color space conversion</title>
+ * <para>
+ * Equivalent to glupload ! gldownload. 
+ * </para>
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-yuv" ! glcolorscale ! ximagesink
+ * ]| A pipeline to test colorspace conversion.
+ * FBO is required.
+  |[
+ * gst-launch -v videotestsrc ! "video/x-raw-yuv, width=640, height=480, format=(fourcc)AYUV" ! glcolorscale ! \
+ *   "video/x-raw-yuv, width=320, height=240, format=(fourcc)YV12" ! autovideosink
+ * ]| A pipeline to test hardware scaling and colorspace conversion.
+ * FBO and GLSL are required.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstgldownload.c b/gst/gl/gstgldownload.c
index 3ed24da..345c74b 100644
--- a/gst/gl/gstgldownload.c
+++ b/gst/gl/gstgldownload.c
@@ -19,6 +19,45 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-gldownload
+ *
+ * download opengl textures into video frames.
+ *
+ * <refsect2>
+ * <title>Color space conversion</title>
+ * <para>
+ * When needed, the color space conversion is made in a fragment shader using 
+ * one frame buffer object instance.
+ * </para>
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-rgb" ! glupload ! gldownload ! \
+ *   "video/x-raw-rgb" ! ximagesink
+ * ]| A pipeline to test downloading.
+ * No special opengl extension is used in this pipeline, that's why it should work
+ * with OpenGL >= 1.1. That's the case if you are using the MESA3D driver v1.3.
+  |[
+ * gst-launch -v videotestsrc ! "video/x-raw-rgb, width=640, height=480" ! glupload ! gldownload ! \
+ *   "video/x-raw-rgb, width=320, height=240" ! ximagesink
+ * ]| A pipeline to test hardware scaling.
+ * Frame buffer extension is required. Inded one FBO is used bettween glupload and gldownload,
+ * because the texture needs to be resized.
+ * |[
+ * gst-launch -v gltestsrc ! gldownload ! xvimagesink
+ * ]| A pipeline to test hardware colorspace conversion.
+ * Your driver must support GLSL (OpenGL Shading Language needs OpenGL >= 2.1). 
+ * Texture RGB32T is converted to one of the 4 following format YUY2, UYVY, I420, YV12 and AYUV,
+ * through some fragment shaders and using one framebuffer (FBO extension OpenGL >= 1.4).
+ * MESA >= 7.1 supports GLSL but it's made in software.
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! gldownload ! "video/x-raw-yuv, format=(fourcc)YUY2" ! glimagesink
+ * ]| A pipeline to test hardware colorspace conversion
+ * FBO and GLSL are required. 
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstglfilterapp.c b/gst/gl/gstglfilterapp.c
index 0cfcd9f..df93c9d 100644
--- a/gst/gl/gstglfilterapp.c
+++ b/gst/gl/gstglfilterapp.c
@@ -18,6 +18,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glfilterapp
+ *
+ * The resize and redraw callbacks can be set from a client code.
+ *
+ * <refsect2>
+ * <title>CLient callbacks</title>
+ * <para>
+ * The graphic scene can be written from a client code through the 
+ * two glfilterapp properties.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Examples</title>
+ * see gst-plugins-gl/tests/examples/generic/recordgraphic
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstglfiltercube.c b/gst/gl/gstglfiltercube.c
index bb82ad0..0178af7 100644
--- a/gst/gl/gstglfiltercube.c
+++ b/gst/gl/gstglfiltercube.c
@@ -18,6 +18,28 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glfiltercube
+ *
+ * The resize and redraw callbacks can be set from a client code.
+ *
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! glfiltercube ! glimagesink
+ * ]| A pipeline to mpa textures on the 6 cube faces..
+ * FBO is required.
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! glfiltercube ! video/x-raw-gl, width=640, height=480 ! glimagesink
+ * ]| Resize scene after drawing the cube.
+ * The scene size is greater than the input video size.
+  |[
+ * gst-launch -v videotestsrc ! glupload ! video/x-raw-gl, width=640, height=480  ! glfiltercube ! glimagesink
+ * ]| Resize scene before drawing the cube.
+ * The scene size is greater than the input video size.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstglfilterglass.c b/gst/gl/gstglfilterglass.c
index e38b6c4..d65d99b 100644
--- a/gst/gl/gstglfilterglass.c
+++ b/gst/gl/gstglfilterglass.c
@@ -19,6 +19,23 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glfilterglass
+ *
+ * Map textures on moving glass.
+ *
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! glfilterglass ! glimagesink
+ * ]| A pipeline inspired from http://www.mdk.org.pl/2007/11/17/gl-colorspace-conversions
+ * FBO is required.
+ * |[
+ * gst-launch -v videotestsrc ! glupload ! glfilterglass ! "video/x-raw-gl, width=640, height=480" ! glimagesink
+ * ]| The scene is greater than the input size.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstglimagesink.c b/gst/gl/gstglimagesink.c
index 3683dc7..87a4bbb 100644
--- a/gst/gl/gstglimagesink.c
+++ b/gst/gl/gstglimagesink.c
@@ -20,6 +20,65 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glimagesink
+ *
+ * glimagesink renders video frames to a drawable on a local or remote
+ * display using OpenGL. This element can receive a Window ID from the 
+ * application through the XOverlay interface and will then render video 
+ * frames in this drawable.
+ * If no Window ID was provided by the application, the element will 
+ * create its own internal window and render into it.
+ *
+ * <refsect2>
+ * <title>Scaling</title>
+ * <para>
+ * Depends on the driver, OpenGL handles hardware accelerated
+ * scaling of video frames. This means that the element will just accept
+ * incoming video frames no matter their geometry and will then put them to the
+ * drawable scaling them on the fly. Using the #GstXvImageSink:force-aspect-ratio
+ * property it is possible to enforce scaling with a constant aspect ratio,
+ * which means drawing black borders around the video frame.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Events</title>
+ * <para>
+ * Through the gl thread, glimagesink handle some events coming from the drawable
+ * to manage its appearance even when the data is not flowing (GST_STATE_PAUSED).
+ * That means that even when the element is paused, it will receive expose events 
+ * from the drawable and draw the latest frame with correct borders/aspect-ratio.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-rgb" ! glimagesink
+ * ]| A pipeline to test hardware scaling.
+ * No special opengl extension is used in this pipeline, that's why it should work
+ * with OpenGL >= 1.1. That's the case if you are using the MESA3D driver v1.3.
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-yuv, format=(fourcc)I420" ! glimagesink
+ * ]| A pipeline to test hardware scaling and hardware colorspace conversion.
+ * When your driver supports GLSL (OpenGL Shading Language needs OpenGL >= 2.1), 
+ * the 4 following format YUY2, UYVY, I420, YV12 and AYUV are converted to RGB32
+ * through some fragment shaders and using one framebuffer (FBO extension OpenGL >= 1.4).
+ * If your driver does not support GLSL but supports MESA_YCbCr extension then
+ * the you can use YUY2 and UYVY. In this case the colorspace conversion is automatically
+ * made when loading the texture and therefore no framebuffer is used.
+ * |[
+ * gst-launch -v gltestsrc ! glimagesink
+ * ]| A pipeline 100% OpenGL.
+ * No special opengl extension is used in this pipeline, that's why it should work
+ * with OpenGL >= 1.1. That's the case if you are using the MESA3D driver v1.3.
+ * |[
+ * gst-plugins-gl/tests/examples/generic/cube
+ * ]| The graphic FPS scene can be greater than the input video FPS.
+ * The graphic scene can be written from a client code through the 
+ * two glfilterapp properties.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstgltestsrc.c b/gst/gl/gstgltestsrc.c
index 1e26f3a..0113e48 100644
--- a/gst/gl/gstgltestsrc.c
+++ b/gst/gl/gstgltestsrc.c
@@ -25,16 +25,16 @@
  *
  * <refsect2>
  * <para>
- * The gltestsrc element is used to produce test video data in a wide variaty
- * of formats. The video test data produced can be controlled with the "pattern"
+ * The gltestsrc element is used to produce test video texture.
+ * The video test produced can be controlled with the "pattern"
  * property.
  * </para>
  * <title>Example launch line</title>
  * <para>
  * <programlisting>
- * gst-launch -v gltestsrc pattern=snow ! ximagesink
+ * gst-launch -v gltestsrc pattern=smpte ! glimagesink
  * </programlisting>
- * Shows random noise in an X window.
+ * Shows original SMPTE color bars in a window.
  * </para>
  * </refsect2>
  */
diff --git a/gst/gl/gstglupload.c b/gst/gl/gstglupload.c
index 5eb3014..2b9cd60 100644
--- a/gst/gl/gstglupload.c
+++ b/gst/gl/gstglupload.c
@@ -19,6 +19,51 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-glupload
+ *
+ * upload video frames video frames into opengl textures.
+ *
+ * <refsect2>
+ * <title>Color space conversion</title>
+ * <para>
+ * Depends on the driver and when needed, the color space conversion is made 
+ * in a fragment shader using one frame buffer object instance, or using
+ * mesa ycbcr .
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-rgb" ! glupload ! glimagesink
+ * ]| A pipeline to test hardware scaling.
+ * No special opengl extension is used in this pipeline, that's why it should work
+ * with OpenGL >= 1.1. That's the case if you are using the MESA3D driver v1.3.
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-yuv, format=(fourcc)I420" ! glupload ! glimagesink
+ * ]| A pipeline to test hardware scaling and hardware colorspace conversion.
+ * When your driver supports GLSL (OpenGL Shading Language needs OpenGL >= 2.1), 
+ * the 4 following format YUY2, UYVY, I420, YV12 and AYUV are converted to RGB32
+ * through some fragment shaders and using one framebuffer (FBO extension OpenGL >= 1.4).
+ * If your driver does not support GLSL but supports MESA_YCbCr extension then
+ * the you can use YUY2 and UYVY. In this case the colorspace conversion is automatically
+ * made when loading the texture and therefore no framebuffer is used.
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-rgb, width=320, height=240" ! glupload ! \
+ *    "video/x-raw-gl, width=640, height=480" ! glimagesink
+ * ]| A pipeline to test hardware scaling.
+ * Frame buffer extension is required. Inded one FBO is used bettween glupload and glimagesink,
+ * because the texture needs to be resized.
+ * |[
+ * gst-launch -v videotestsrc ! "video/x-raw-yuv, width=320, height=240" ! glupload ! \
+ *    "video/x-raw-gl, width=640, height=480" ! glimagesink
+ * ]| A pipeline to test hardware scaling.
+ * Frame buffer extension is required. Inded one FBO is used bettween glupload and glimagesink,
+ * because the texture needs to be resized. Depends on your driver the color space conversion 
+ * is made in a fragment shader using one frame buffer object instance, or using mesa ycbcr .
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
diff --git a/gst/gl/gstopengl.c b/gst/gl/gstopengl.c
index aa70612..4dec7fe 100644
--- a/gst/gl/gstopengl.c
+++ b/gst/gl/gstopengl.c
@@ -21,6 +21,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:plugin-opengl
+ *
+ * Cross-platform OpenGL plugin.
+ * <refsect2>
+ * <title>Debugging</title>
+ * </refsect2>
+ * <refsect2>
+ * <title>Examples</title>
+ * |[
+ * gst-launch-0.10 --gst-debug=gldisplay:3 videotestsrc ! glimagesink
+ * ]| A debugging pipeline.
+  |[
+ * GST_GL_SHADER_DEBUG=1 gst-launch-0.10 videotestsrc ! glimagesink
+ * ]| A debugging pipelines related to shaders.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif