gegl r2846 - in trunk: . gegl/property-types

[ok svn gnome org]

Author: ok
Date: Thu Jan  1 19:34:46 2009
New Revision: 2846
URL: http://svn.gnome.org/viewvc/gegl?rev=2846&view=rev

Log:
* gegl/property-types/gegl-color.c:
* gegl/property-types/gegl-color.h:
* gegl/property-types/gegl-curve.h: Added documentation of public
methods of GeglColor and GeglCurve.
* gegl/property-types/gegl-path.h: formatting update.


Modified:
   trunk/ChangeLog
   trunk/gegl/property-types/gegl-color.c
   trunk/gegl/property-types/gegl-color.h
   trunk/gegl/property-types/gegl-curve.h
   trunk/gegl/property-types/gegl-path.h

Modified: trunk/gegl/property-types/gegl-color.c
==============================================================================
--- trunk/gegl/property-types/gegl-color.c	(original)
+++ trunk/gegl/property-types/gegl-color.c	Thu Jan  1 19:34:46 2009
@@ -478,6 +478,7 @@
   parent_class->finalize (self);
 }
 
+#if 0
 static void
 value_set_default (GParamSpec *param_spec,
                    GValue     *value)
@@ -486,6 +487,7 @@
 
   g_value_set_object (value, gegl_color->default_color);
 }
+#endif
 
 GType
 gegl_param_color_get_type (void)

Modified: trunk/gegl/property-types/gegl-color.h
==============================================================================
--- trunk/gegl/property-types/gegl-color.h	(original)
+++ trunk/gegl/property-types/gegl-color.h	Thu Jan  1 19:34:46 2009
@@ -44,22 +44,71 @@
 
 GType        gegl_color_get_type               (void) G_GNUC_CONST;
 
+
+/***
+ * GeglColor:
+ *
+ * GeglColor is an object containing a color at the moment only RGB colors
+ * are supported, in the future a GeglColor might also indicate other
+ * enumerated or natively in other color representations colors.
+ */
+
+/**
+ * gegl_color_new:
+ * @string: a string describing the color to be created.
+ *
+ * Creates a new #GeglColor.
+ *
+ * Returns the newly created #GeglColor.
+ */
 GeglColor *  gegl_color_new                    (const gchar *string);
 
-void         gegl_color_get_rgba               (GeglColor   *self,
+/**
+ * gegl_color_get_rgba:
+ * @color: a #GeglColor
+ * @r: red return location.
+ * @g: green return location.
+ * @b: blue return location.
+ * @a: alpha return location.
+ *
+ * Retrieves the current set color as linear light non premultipled RGBA data,
+ * any of the return pointers can be omitted.
+ */
+void         gegl_color_get_rgba               (GeglColor   *color,
                                                 gfloat      *r,
                                                 gfloat      *g,
                                                 gfloat      *b,
                                                 gfloat      *a);
 
-void         gegl_color_set_rgba               (GeglColor   *self,
+/**
+ * gegl_color_set_rgba:
+ * @color: a #GeglColor
+ * @r: red value
+ * @g: green value
+ * @b: blue value
+ * @a: alpha value
+ *
+ * Retrieves the current set color as linear light non premultipled RGBA data
+ */
+void         gegl_color_set_rgba               (GeglColor   *color,
                                                 gfloat       r,
                                                 gfloat       g,
                                                 gfloat       b,
                                                 gfloat       a);
 
+/**
+ * gegl_color_float4:
+ * @color: a #GeglColor
+ *
+ * Returns a direct pointer to the internal representation
+ * XXX: should probably be removed from the public API.
+ */
 const gfloat*gegl_color_float4                 (GeglColor *color);
 
+
+/***
+ */
+
 #define GEGL_TYPE_PARAM_COLOR           (gegl_param_color_get_type ())
 #define GEGL_IS_PARAM_SPEC_COLOR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GEGL_TYPE_PARAM_COLOR))
 

Modified: trunk/gegl/property-types/gegl-curve.h
==============================================================================
--- trunk/gegl/property-types/gegl-curve.h	(original)
+++ trunk/gegl/property-types/gegl-curve.h	Thu Jan  1 19:34:46 2009
@@ -19,6 +19,14 @@
 #ifndef __GEGL_CURVE_H__
 #define __GEGL_CURVE_H__
 
+/***
+ * GeglCurve:
+ *
+ * #GeglCurve is a curve describing a unique mapping of values.
+ *
+ * Used for things like the curves widget in gimp it is a form of doodle
+ * alpha.
+ */
 #include <glib-object.h>
 
 G_BEGIN_DECLS
@@ -44,51 +52,121 @@
 
 GType        gegl_curve_get_type       (void) G_GNUC_CONST;
 
+/**
+ * gegl_curve_new:
+ * @y_min: minimum y value for curve.
+ * @y_max: maximum y value for curve.
+ *
+ * Create a #GeglCurve that can store a curve with values between @y_min and
+ * @y_max.
+ *
+ * Returns the newly created #GeglCurve.
+ */
 GeglCurve  * gegl_curve_new            (gdouble      y_min,
                                         gdouble      y_max);
 
-GeglCurve  * gegl_curve_default_curve  (void) G_GNUC_CONST;
 
-void         gegl_curve_get_y_bounds   (GeglCurve   *self,
-                                        gdouble     *min_y,
-                                        gdouble     *max_y);
-/* should perhaps become: */
-void         gegl_curve_get_bounds     (GeglCurve   *self,
-                                        gdouble     *min_x,
-                                        gdouble     *max_x,
+/**
+ * gegl_curve_get_y_bounds:
+ * @curve: a #GeglCurve.
+ * @min_y: return location for minimal value.
+ * @max_y: return location for maximal value.
+ *
+ * Get the bounds on the values of the curve and store the values in
+ * the return locaitons provided in @min_y and @max_y.
+ */
+void         gegl_curve_get_y_bounds   (GeglCurve   *curve,
                                         gdouble     *min_y,
                                         gdouble     *max_y);
 
-guint        gegl_curve_add_point      (GeglCurve   *self,
+/**
+ * gegl_curve_add_point:
+ * @curve: a #GeglCurve.
+ * @x: x coordinate
+ * @y: y coordinate
+ *
+ * Add a point to the curve at @x @y (replacing the value exactly for @x if it
+ * already exists.
+ */
+guint        gegl_curve_add_point      (GeglCurve   *curve,
                                         gdouble      x,
                                         gdouble      y);
 
-void         gegl_curve_get_point      (GeglCurve   *self,
+/**
+ * gegl_curve_get_point:
+ * @curve: a #GeglCurve.
+ * @index: the position of the value number to retrieve.
+ * @x: x coordinate return location.
+ * @y: y coordinate return location.
+ *
+ * Retrive the coordinates for an index.
+ */
+void         gegl_curve_get_point      (GeglCurve   *curve,
                                         guint        index,
                                         gdouble     *x,
                                         gdouble     *y);
 
-void         gegl_curve_set_point      (GeglCurve   *self,
+/**
+ * gegl_curve_set_point:
+ * @curve: a #GeglCurve.
+ * @index: the position of the value number to retrieve.
+ * @x: x coordinate
+ * @y: y coordinate
+ *
+ * Replace an existing point in a curve.
+ */
+void         gegl_curve_set_point      (GeglCurve   *curve,
                                         guint        index,
                                         gdouble      x,
                                         gdouble      y);
 
-guint        gegl_curve_num_points     (GeglCurve   *self);
-
-gdouble      gegl_curve_calc_value     (GeglCurve   *self,
+/**
+ * gegl_curve_num_points:
+ * @curve: a #GeglCurve.
+ *
+ * Retrieve the number of points in the curve.
+ *
+ * Returns the number of points for the coordinates in the curve.
+ */
+guint        gegl_curve_num_points     (GeglCurve   *curve);
+
+/**
+ * gegl_curve_calc_value:
+ * @curve: a #GeglCurve.
+ *
+ * Retrieve the number of points in the curve.
+ *
+ * Returns the number of points for the coordinates in the curve.
+ */
+gdouble      gegl_curve_calc_value     (GeglCurve   *curve,
                                         gdouble      x);
 
-void         gegl_curve_calc_values    (GeglCurve   *self,
+/**
+ * gegl_curve_calc_values:
+ * @curve: a #GeglCurve.
+ * @x_min: the minimum value to compute for
+ * @x_max: the maxmimum value to compute for
+ * @num_samples: number of samples to calculate
+ * @xs: return location for the x coordinates
+ * @ys: return location for the y coordinates
+ *
+ * Compute a set (lookup table) of coordinates.
+ */
+void         gegl_curve_calc_values    (GeglCurve   *curve,
                                         gdouble      x_min,
                                         gdouble      x_max,
                                         guint        num_samples,
                                         gdouble     *xs,
                                         gdouble     *ys);
 
+/***
+ */
 
 #define GEGL_TYPE_PARAM_CURVE           (gegl_param_curve_get_type ())
 #define GEGL_IS_PARAM_SPEC_CURVE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GEGL_TYPE_PARAM_CURVE))
 
+GeglCurve  * gegl_curve_default_curve  (void) G_GNUC_CONST;
+
 GType        gegl_param_curve_get_type (void) G_GNUC_CONST;
 
 GParamSpec * gegl_param_spec_curve     (const gchar *name,

Modified: trunk/gegl/property-types/gegl-path.h
==============================================================================
--- trunk/gegl/property-types/gegl-path.h	(original)
+++ trunk/gegl/property-types/gegl-path.h	Thu Jan  1 19:34:46 2009
@@ -358,6 +358,9 @@
  */
 void gegl_path_thaw (GeglPath *path);
 
+/***
+ * :
+ */
 
 GParamSpec         * gegl_param_spec_path     (const gchar *name,
                                                const gchar *nick,
@@ -400,9 +403,6 @@
  */
 void gegl_path_add_flattener (GeglPathList *(*func) (GeglPathList *original));
 
-/**
- * foo:
- */
 
 G_END_DECLS