* clutter/clutter-frame-source.c (clutter_frame_source_add)

(clutter_frame_source_add_full): Add gtk-doc and rename the
	'function' parameter to 'func'.

	* clutter/clutter-frame-source.h: Rename the 'function' parameters
	to 'func'.

	* clutter/Makefile.am (source_h): Make clutter-frame-source.h a
	public header.

	* clutter/clutter-main.c (clutter_threads_add_frame_source_full):
	Improve gtk-doc

	* doc/reference/clutter/clutter-sections.txt: Added
	clutter_threads_add_frame_source,
	clutter_threads_add_frame_source_full,
	clutter_frame_source_add and clutter_frame_source_add_full.

ChangeLog

@@ -1,3 +1,18 @@
+2008-05-09  Neil Roberts  <neil@o-hand.com>
+
+	* clutter/clutter-frame-source.c (clutter_frame_source_add)
+	(clutter_frame_source_add_full): Add gtk-doc and rename the
+	'function' parameter to 'func'.
+
+	* clutter/clutter-frame-source.h: Rename the 'function' parameters
+	to 'func'.
+
+	* clutter/Makefile.am (source_h): Make clutter-frame-source.h a
+	public header.
+
+	* clutter/clutter-main.c (clutter_threads_add_frame_source_full):
+	Improve gtk-doc
+
 2008-05-09  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/clutter-script-private.h: Add a flag for the

clutter/Makefile.am

@@ -67,6 +67,7 @@ source_h =					\
 	$(srcdir)/clutter-event.h 		\
 	$(srcdir)/clutter-feature.h 		\
 	$(srcdir)/clutter-fixed.h 		\
+	$(srcdir)/clutter-frame-source.h        \
 	$(srcdir)/clutter-group.h 		\
 	$(srcdir)/clutter-keysyms.h 		\
 	$(srcdir)/clutter-label.h 		\
@@ -178,7 +179,6 @@ source_c = \
 
 source_h_priv = \
 	clutter-debug.h 		\
-	clutter-frame-source.h          \
 	clutter-keysyms-table.h		\
 	clutter-model-private.h		\
 	clutter-private.h 		\

clutter/clutter-frame-source.c

@@ -53,10 +53,40 @@ static GSourceFuncs clutter_frame_source_funcs =
     NULL
   };
 
+/**
+ * clutter_frame_source_add_full:
+ * @priority: the priority of the frame source. Typically this will be in the
+ *            range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
+ * @interval: the time between calls to the function, in milliseconds
+ * @func: function to call
+ * @data: data to pass to the function
+ * @notify: function to call when the timeout source is removed
+ *
+ * Sets a function to be called at regular intervals with the given
+ * priority.  The function is called repeatedly until it returns
+ * %FALSE, at which point the timeout is automatically destroyed and
+ * the function will not be called again.  The @notify function is
+ * called when the timeout is destroyed.  The first call to the
+ * function will be at the end of the first @interval.
+ *
+ * This function is similar to g_timeout_add_full() except that it
+ * will try to compensate for delays. For example, if @func takes half
+ * the interval time to execute then the function will be called again
+ * half the interval time after it finished. In contrast
+ * g_timeout_add_full() would not fire until a full interval after the
+ * function completes so the delay between calls would be @interval *
+ * 1.5. This function does not however try to invoke the function
+ * multiple times to catch up missing frames if @func takes more than
+ * @interval ms to execute.
+ *
+ * Return value: the ID (greater than 0) of the event source.
+ *
+ * Since: 0.8
+ */
 guint
 clutter_frame_source_add_full (gint           priority,
 			       guint          interval,
-			       GSourceFunc    function,
+			       GSourceFunc    func,
 			       gpointer       data,
 			       GDestroyNotify notify)
 {
@@ -72,7 +102,7 @@ clutter_frame_source_add_full (gint           priority,
   if (priority != G_PRIORITY_DEFAULT)
     g_source_set_priority (source, priority);
 
-  g_source_set_callback (source, function, data, notify);
+  g_source_set_callback (source, func, data, notify);
 
   ret = g_source_attach (source, NULL);
 
@@ -81,13 +111,25 @@ clutter_frame_source_add_full (gint           priority,
   return ret;
 }
 
+/**
+ * clutter_frame_source_add:
+ * @interval: the time between calls to the function, in milliseconds
+ * @func: function to call
+ * @data: data to pass to the function
+ *
+ * Simple wrapper around clutter_frame_source_add_full().
+ *
+ * Return value: the ID (greater than 0) of the event source.
+ *
+ * Since: 0.8
+ */
 guint
 clutter_frame_source_add (guint          interval,
-			  GSourceFunc    function,
+			  GSourceFunc    func,
 			  gpointer       data)
 {
   return clutter_frame_source_add_full (G_PRIORITY_DEFAULT,
-					interval, function, data, NULL);
+					interval, func, data, NULL);
 }
 
 static guint

clutter/clutter-frame-source.h

@@ -31,12 +31,12 @@
 G_BEGIN_DECLS
 
 guint clutter_frame_source_add (guint          interval,
-				GSourceFunc    function,
+				GSourceFunc    func,
 				gpointer       data);
 
 guint clutter_frame_source_add_full (gint           priority,
 				     guint          interval,
-				     GSourceFunc    function,
+				     GSourceFunc    func,
 				     gpointer       data,
 				     GDestroyNotify notify);
 

clutter/clutter-main.c

@@ -682,16 +682,19 @@ clutter_threads_add_timeout (guint       interval,
  * called when the timeout is destroyed.  The first call to the
  * function will be at the end of the first @interval.
  *
- * This function is similar to clutter_threads_add_timeout_full except
+ * This function is similar to clutter_threads_add_timeout_full()
- * that it will try to compensate for delays. For example, if @func
+ * except that it will try to compensate for delays. For example, if
- * takes half the interval time to execute then the function will be
+ * @func takes half the interval time to execute then the function
- * called again half the interval time after it finished. In contrast
+ * will be called again half the interval time after it finished. In
- * clutter_threads_add_timeout_full would not fire until a full
+ * contrast clutter_threads_add_timeout_full() would not fire until a
- * interval after the function completes so the delay between calls
+ * full interval after the function completes so the delay between
- * would be @interval * 1.5. This function does not however try to
+ * calls would be @interval * 1.5. This function does not however try
- * invoke the function multiple times to catch up missing frames if
+ * to invoke the function multiple times to catch up missing frames if
  * @func takes more than @interval ms to execute.
  *
+ * This variant of clutter_frame_source_add_full() can be thought of a
+ * MT-safe version for Clutter actors.
+
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 0.8

doc/reference/ChangeLog

@@ -1,3 +1,10 @@
+2008-05-09  Neil Roberts  <neil@o-hand.com>
+
+	* clutter/clutter-sections.txt: Added
+	clutter_threads_add_frame_source,
+	clutter_threads_add_frame_source_full, clutter_frame_source_add
+	and clutter_frame_source_add_full.
+
 2008-04-29  Neil Roberts  <neil@o-hand.com>
 
 	* cogl/cogl-sections.txt: Added cogl_shader_ref,

doc/reference/clutter/clutter-sections.txt

@@ -963,6 +963,12 @@ clutter_threads_add_idle
 clutter_threads_add_idle_full
 clutter_threads_add_timeout
 clutter_threads_add_timeout_full
+clutter_threads_add_frame_source
+clutter_threads_add_frame_source_full
+
+<SUBSECTION>
+clutter_frame_source_add
+clutter_frame_source_add_full
 
 <SUBSECTION>
 clutter_get_keyboard_grab