More and more documentation.

Original commit message from CVS:
2005-11-27  Julien MOUTTE  <julien@moutte.net>

* docs/libs/tmpl/gstcolorbalance.sgml:
* docs/libs/tmpl/gstmixer.sgml:
* docs/libs/tmpl/gstxoverlay.sgml:
* sys/ximage/ximagesink.c: (gst_ximagesink_buffer_alloc):
* sys/ximage/ximagesink.h:
* sys/xvimage/xvimagesink.h: More and more documentation.

ChangeLog

@@ -1,3 +1,12 @@
+2005-11-27  Julien MOUTTE  <julien@moutte.net>
+
+	* docs/libs/tmpl/gstcolorbalance.sgml:
+	* docs/libs/tmpl/gstmixer.sgml:
+	* docs/libs/tmpl/gstxoverlay.sgml:
+	* sys/ximage/ximagesink.c: (gst_ximagesink_buffer_alloc):
+	* sys/ximage/ximagesink.h:
+	* sys/xvimage/xvimagesink.h: More and more documentation.
+
 2005-11-26  Julien MOUTTE  <julien@moutte.net>
 
 	* docs/libs/gst-plugins-base-libs-docs.sgml:

docs/libs/tmpl/gstcolorbalance.sgml

@@ -23,6 +23,15 @@ gstcolorbalance
 </para>
 
 
+<!-- ##### SIGNAL GstColorBalance::value-changed ##### -->
+<para>
+
+</para>
+
+@gstcolorbalance: the object which received the signal.
+@arg1: 
+@arg2: 
+
 <!-- ##### STRUCT GstColorBalanceClass ##### -->
 <para>
 

docs/libs/tmpl/gstmixer.sgml

@@ -47,18 +47,12 @@ gstmixer
 
 </para>
 
-@parent: 
-@values: 
-@_gst_reserved: 
 
 <!-- ##### STRUCT GstMixerTrack ##### -->
 <para>
 
 </para>
 
-@parent: 
-@label: 
-@flags: 
 
 <!-- ##### FUNCTION gst_mixer_list_tracks ##### -->
 <para>

docs/libs/tmpl/gstxoverlay.sgml

@@ -9,13 +9,11 @@ gstxoverlay
 
 </para>
 
-
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### SECTION Stability_Level ##### -->
 
 

sys/ximage/ximagesink.c

@@ -1516,6 +1516,7 @@ alloc:
       }
     }
   }
+  g_mutex_unlock (ximagesink->pool_lock);
 
   /* We haven't found anything, creating a new one */
   if (!ximage) {
@@ -1533,7 +1534,6 @@ alloc:
       gst_buffer_set_caps (GST_BUFFER (ximage), caps);
     }
   }
-  g_mutex_unlock (ximagesink->pool_lock);
 
   gst_caps_unref (desired_caps);
 

sys/ximage/ximagesink.h

@@ -60,7 +60,31 @@ typedef struct _GstXImageBufferClass GstXImageBufferClass;
 typedef struct _GstXImageSink GstXImageSink;
 typedef struct _GstXImageSinkClass GstXImageSinkClass;
 
-/* Global X Context stuff */
+/**
+ * GstXContext:
+ * @disp: the X11 Display of this context
+ * @screen: the default Screen of Display @disp
+ * @screen_num: the Screen number of @screen
+ * @visual: the default Visual of Screen @screen
+ * @root: the root Window of Display @disp
+ * @white: the value of a white pixel on Screen @screen
+ * @black: the value of a black pixel on Screen @screen
+ * @depth: the color depth of Display @disp
+ * @bpp: the number of bits per pixel on Display @disp
+ * @endianness: the endianness of image bytes on Display @disp
+ * @width: the width in pixels of Display @disp
+ * @height: the height in pixels of Display @disp
+ * @widthmm: the width in millimeters of Display @disp
+ * @heightmm: the height in millimeters of Display @disp
+ * @par: the pixel aspect ratio calculated from @width, @widthmm and @height, 
+ * @heightmm ratio
+ * @use_xshm: used to known wether of not XShm extension is usable or not even
+ * if the Extension is present
+ * @caps: the #GstCaps that Display @disp can accept
+ *
+ * Structure used to store various informations collected/calculated for a
+ * Display.
+ */
 struct _GstXContext {
   Display *disp;
 
@@ -86,7 +110,17 @@ struct _GstXContext {
   GstCaps *caps;
 };
 
-/* XWindow stuff */
+/**
+ * GstXWindow:
+ * @win: the Window ID of this X11 window
+ * @width: the width in pixels of Window @win
+ * @height: the height in pixels of Window @win
+ * @internal: used to remember if Window @win was created internally or passed
+ * through the #GstXOverlay interface
+ * @gc: the Graphical Context of Window @win
+ *
+ * Structure used to store informations about a Window.
+ */
 struct _GstXWindow {
   Window win;
   gint width, height;
@@ -94,7 +128,16 @@ struct _GstXWindow {
   GC gc;
 };
 
-/* XImage stuff */
+/**
+ * GstXImageBuffer:
+ * @ximagesink: a reference to our #GstXImageSink
+ * @ximage: the XImage of this buffer
+ * @width: the width in pixels of XImage @ximage
+ * @height: the height in pixels of XImage @ximage
+ * @size: the size in bytes of XImage @ximage
+ *
+ * Subclass of #GstBuffer containing additional information about an XImage.
+ */
 struct _GstXImageBuffer {
   GstBuffer buffer;
 
@@ -111,6 +154,34 @@ struct _GstXImageBuffer {
   size_t size;
 };
 
+/**
+ * GstXImageSink:
+ * @display_name: the name of the Display we want to render to
+ * @xcontext: our instance's #GstXContext
+ * @xwindow: the #GstXWindow we are rendering to
+ * @ximage: internal #GstXImage used to store incoming buffers and render when
+ * not using the buffer_alloc optimization mechanism
+ * @cur_image: a reference to the last #GstXImage that was put to @xwindow. It
+ * is used when Expose events are received to redraw the latest video frame
+ * @event_thread: a thread listening for events on @xwindow and handling them
+ * @running: used to inform @event_thread if it should run/shutdown
+ * @fps_n: the framerate fraction numerator
+ * @fps_d: the framerate fraction denominator
+ * @x_lock: used to protect X calls as we are not using the XLib in threaded
+ * mode
+ * @flow_lock: used to protect data flow routines from external calls such as
+ * events from @event_thread or methods from the #GstXOverlay interface
+ * @par: used to override calculated pixel aspect ratio from @xcontext
+ * @pool_lock: used to protect the buffer pool
+ * @buffer_pool: a list of #GstXImageBuffer that could be reused at next buffer
+ * allocation call
+ * @synchronous: used to store if XSynchronous should be used or not (for 
+ * debugging purpose only)
+ * @keep_aspect: used to remember if reverse negotiation scaling should respect
+ * aspect ratio
+ *
+ * The #GstXImageSink data structure.
+ */
 struct _GstXImageSink {
   /* Our element stuff */
   GstVideoSink videosink;
@@ -131,10 +202,9 @@ struct _GstXImageSink {
 
   GMutex *x_lock;
   GMutex *flow_lock;
-
+  
-  /* Unused */
+  /* object-set pixel aspect ratio */
-  gint pixel_width, pixel_height;
+  GValue *par;
-  GValue *par;                  /* object-set pixel aspect ratio */
 
   GMutex *pool_lock;
   GSList *buffer_pool;

sys/xvimage/xvimagesink.h

@@ -63,7 +63,35 @@ typedef struct _GstXvImageBufferClass GstXvImageBufferClass;
 typedef struct _GstXvImageSink GstXvImageSink;
 typedef struct _GstXvImageSinkClass GstXvImageSinkClass;
 
-/* Global X Context stuff */
+/**
+ * GstXContext:
+ * @disp: the X11 Display of this context
+ * @screen: the default Screen of Display @disp
+ * @screen_num: the Screen number of @screen
+ * @visual: the default Visual of Screen @screen
+ * @root: the root Window of Display @disp
+ * @white: the value of a white pixel on Screen @screen
+ * @black: the value of a black pixel on Screen @screen
+ * @depth: the color depth of Display @disp
+ * @bpp: the number of bits per pixel on Display @disp
+ * @endianness: the endianness of image bytes on Display @disp
+ * @width: the width in pixels of Display @disp
+ * @height: the height in pixels of Display @disp
+ * @widthmm: the width in millimeters of Display @disp
+ * @heightmm: the height in millimeters of Display @disp
+ * @par: the pixel aspect ratio calculated from @width, @widthmm and @height, 
+ * @heightmm ratio
+ * @use_xshm: used to known wether of not XShm extension is usable or not even
+ * if the Extension is present
+ * @xv_port_id: the XVideo port ID
+ * @im_format: used to store at least a valid format for XShm calls checks
+ * @formats_list: list of supported image formats on @xv_port_id
+ * @channels_list: list of #GstColorBalanceChannels
+ * @caps: the #GstCaps that Display @disp can accept
+ *
+ * Structure used to store various informations collected/calculated for a
+ * Display.
+ */
 struct _GstXContext {
   Display *disp;
 
@@ -95,7 +123,17 @@ struct _GstXContext {
   GstCaps *caps;
 };
 
-/* XWindow stuff */
+/**
+ * GstXWindow:
+ * @win: the Window ID of this X11 window
+ * @width: the width in pixels of Window @win
+ * @height: the height in pixels of Window @win
+ * @internal: used to remember if Window @win was created internally or passed
+ * through the #GstXOverlay interface
+ * @gc: the Graphical Context of Window @win
+ *
+ * Structure used to store informations about a Window.
+ */
 struct _GstXWindow {
   Window win;
   gint width, height;
@@ -103,13 +141,29 @@ struct _GstXWindow {
   GC gc;
 };
 
-/* XvImage format stuff */
+/**
+ * GstXvImageFormat:
+ * @format: the image format
+ * @caps: generated #GstCaps for this image format
+ *
+ * Structure storing image format to #GstCaps association.
+ */
 struct _GstXvImageFormat {
   gint format;
   GstCaps *caps;
 };
 
-/* XvImage stuff */
+/**
+ * GstXImageBuffer:
+ * @xvimagesink: a reference to our #GstXvImageSink
+ * @xvimage: the XvImage of this buffer
+ * @width: the width in pixels of XvImage @xvimage
+ * @height: the height in pixels of XvImage @xvimage
+ * @im_format: the image format of XvImage @xvimage
+ * @size: the size in bytes of XvImage @xvimage
+ *
+ * Subclass of #GstBuffer containing additional information about an XvImage.
+ */
 struct _GstXvImageBuffer {
   GstBuffer   buffer;
 
@@ -122,9 +176,45 @@ struct _GstXvImageBuffer {
   XShmSegmentInfo SHMInfo;
 #endif /* HAVE_XSHM */
 
-  gint width, height, size, im_format;
+  gint width, height, im_format;
+  size_t size;
 };
 
+/**
+ * GstXvImageSink:
+ * @display_name: the name of the Display we want to render to
+ * @xcontext: our instance's #GstXContext
+ * @xwindow: the #GstXWindow we are rendering to
+ * @xvimage: internal #GstXvImage used to store incoming buffers and render when
+ * not using the buffer_alloc optimization mechanism
+ * @cur_image: a reference to the last #GstXvImage that was put to @xwindow. It
+ * is used when Expose events are received to redraw the latest video frame
+ * @event_thread: a thread listening for events on @xwindow and handling them
+ * @running: used to inform @event_thread if it should run/shutdown
+ * @fps_n: the framerate fraction numerator
+ * @fps_d: the framerate fraction denominator
+ * @x_lock: used to protect X calls as we are not using the XLib in threaded
+ * mode
+ * @flow_lock: used to protect data flow routines from external calls such as
+ * events from @event_thread or methods from the #GstXOverlay interface
+ * @par: used to override calculated pixel aspect ratio from @xcontext
+ * @pool_lock: used to protect the buffer pool
+ * @image_pool: a list of #GstXvImageBuffer that could be reused at next buffer
+ * allocation call
+ * @synchronous: used to store if XSynchronous should be used or not (for 
+ * debugging purpose only)
+ * @keep_aspect: used to remember if reverse negotiation scaling should respect
+ * aspect ratio
+ * @brightness: used to store the user settings for color balance brightness
+ * @contrast: used to store the user settings for color balance contrast
+ * @hue: used to store the user settings for color balance hue
+ * @saturation: used to store the user settings for color balance saturation
+ * @cb_changed: used to store if the color balance settings where changed
+ * @video_width: the width of incoming video frames in pixels
+ * @video_height: the height of incoming video frames in pixels
+ *
+ * The #GstXvImageSink data structure.
+ */
 struct _GstXvImageSink {
   /* Our element stuff */
   GstVideoSink videosink;
@@ -135,31 +225,33 @@ struct _GstXvImageSink {
   GstXWindow *xwindow;
   GstXvImageBuffer *xvimage;
   GstXvImageBuffer *cur_image;
+  
+  GThread *event_thread;
+  gboolean running;
 
   gint fps_n;
   gint fps_d;
+  
+  GMutex *x_lock;
+  GMutex *flow_lock;
 
+  /* object-set pixel aspect ratio */
+  GValue *par;
+  
+  GMutex *pool_lock;
+  GSList *image_pool;
+  
+  gboolean synchronous;
+  gboolean keep_aspect;
+  
   gint brightness;
   gint contrast;
   gint hue;
   gint saturation;
   gboolean cb_changed;
 
-  GMutex *x_lock;
-  GMutex *flow_lock;
-  
-  GThread *event_thread;
-
   guint video_width, video_height;     /* size of incoming video;
                                         * used as the size for XvImage */
-  GValue *par;                         /* object-set pixel aspect ratio */
-
-  GMutex *pool_lock;
-  GSList *image_pool;
-
-  gboolean synchronous;
-  gboolean running;
-  gboolean keep_aspect;
 };
 
 struct _GstXvImageSinkClass {