gegl r2849 - in trunk: . docs gegl

[ok svn gnome org]

Author: ok
Date: Fri Jan  2 02:31:02 2009
New Revision: 2849
URL: http://svn.gnome.org/viewvc/gegl?rev=2849&view=rev

Log:
* docs/Makefile.am: add gegl-utils.h
* gegl/gegl-utils.h: documented.
* gegl/gegl.h.in: do not document the GeglRectangle struct here but in
gegl-utils.h


Modified:
   trunk/ChangeLog
   trunk/docs/Makefile.am
   trunk/gegl/gegl-utils.h
   trunk/gegl/gegl.h.in

Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am	(original)
+++ trunk/docs/Makefile.am	Fri Jan  2 02:31:02 2009
@@ -132,17 +132,21 @@
 
 api.html: $(top_srcdir)/gegl/gegl.h\
           $(top_srcdir)/gegl/buffer/gegl-buffer.h\
-          $(top_srcdir)/gegl/property-types/gegl-curve.h\
-          $(top_srcdir)/gegl/property-types/gegl-path.h\
+          $(top_srcdir)/gegl/gegl-utils.h\
           $(top_srcdir)/gegl/property-types/gegl-color.h\
+          $(top_srcdir)/gegl/gegl-matrix.h\
+          $(top_srcdir)/gegl/property-types/gegl-path.h\
+          $(top_srcdir)/gegl/property-types/gegl-curve.h\
 	  $(top_srcdir)/tools/create-reference.rb
 if HAVE_RUBY
 	$(top_srcdir)/tools/create-reference.rb 	\
 	    $(top_srcdir)/gegl/gegl.h			\
 	    $(top_srcdir)/gegl/buffer/gegl-buffer.h	\
+            $(top_srcdir)/gegl/gegl-utils.h \
+            $(top_srcdir)/gegl/property-types/gegl-color.h\
+            $(top_srcdir)/gegl/gegl-matrix.h \
             $(top_srcdir)/gegl/property-types/gegl-path.h\
             $(top_srcdir)/gegl/property-types/gegl-curve.h\
-            $(top_srcdir)/gegl/property-types/gegl-color.h\
 	    $@
 endif
 

Modified: trunk/gegl/gegl-utils.h
==============================================================================
--- trunk/gegl/gegl-utils.h	(original)
+++ trunk/gegl/gegl-utils.h	Fri Jan  2 02:31:02 2009
@@ -16,33 +16,159 @@
  * Copyright 2003 Calvin Williamson
  */
 
+
 #ifndef __GEGL_UTILS_H__
 #define __GEGL_UTILS_H__
 
 G_BEGIN_DECLS
 
-void        gegl_rectangle_set           (GeglRectangle       *r,
+
+
+
+/***
+ * GeglRectangle:
+ *
+ * GeglRectangles are used in #gegl_node_get_bounding_box and #gegl_node_blit
+ * for specifying rectangles.
+ *
+ * </p><pre>struct GeglRectangle
+ * {
+ *   gint x;
+ *   gint y;
+ *   gint width;
+ *   gint height;
+ * };</pre><p>
+ *
+ */
+
+/**
+ * gegl_rectangle_set:
+ * @rectangle: a #GeglRectangle
+ * @x: upper left x coordinate
+ * @y: upper left y coordinate
+ * @width: width in pixels.
+ * @height: height in pixels.
+ *
+ * Sets the @x, @y, @width and @height on @rectangle.
+ */
+void        gegl_rectangle_set           (GeglRectangle       *rectangle,
                                           gint                 x,
                                           gint                 y,
                                           guint                width,
                                           guint                height);
-gboolean    gegl_rectangle_equal         (const GeglRectangle *r,
-                                          const GeglRectangle *s);
-gboolean    gegl_rectangle_equal_coords  (const GeglRectangle *r,
+
+/**
+ * gegl_rectangle_equal:
+ * @rectangle1: a #GeglRectangle
+ * @rectangle2: a #GeglRectangle
+ *
+ * Check if two #GeglRectangles are equal.
+ *
+ * Returns TRUE if @rectangle and @rectangle2 are equal.
+ */
+gboolean    gegl_rectangle_equal         (const GeglRectangle *rectangle1,
+                                          const GeglRectangle *rectangle2);
+
+/**
+ * gegl_rectangle_equal_coords:
+ * @rectangle: a #GeglRectangle
+ * @x: X coordinate
+ * @y: Y coordinate
+ * @width: width of rectangle
+ * @height: height of rectangle
+ *
+ * Check if a rectangle is equal to a set of parameters.
+ *
+ * Returns TRUE if @rectangle and @x,@y @width x @height are equal.
+ */
+gboolean    gegl_rectangle_equal_coords  (const GeglRectangle *rectangle,
                                           gint                 x,
                                           gint                 y,
                                           gint                 width,
                                           gint                 height);
-void        gegl_rectangle_copy          (GeglRectangle       *to,
-                                          const GeglRectangle *from);
-void        gegl_rectangle_bounding_box  (GeglRectangle       *dest,
-                                          const GeglRectangle *src1,
-                                          const GeglRectangle *src2);
+
+/**
+ * gegl_rectangle_copy:
+ * @destination: a #GeglRectangle
+ * @source: a #GeglRectangle
+ *
+ * Copies the rectangle information stored in @source over the information in
+ * @destination.
+ */
+void        gegl_rectangle_copy          (GeglRectangle       *destination,
+                                          const GeglRectangle *source);
+
+/**
+ * gegl_rectangle_bounding_box:
+ * @destination: a #GeglRectangle
+ * @source1: a #GeglRectangle
+ * @source2: a #GeglRectangle
+ *
+ * Computes the bounding box of the rectangles @source1 and @source2 and stores the
+ * resulting bounding box in @destination.
+ */
+void        gegl_rectangle_bounding_box  (GeglRectangle       *destination,
+                                          const GeglRectangle *source1,
+                                          const GeglRectangle *source2);
+
+/**
+ * gegl_rectangle_intersect:
+ * @dest: return location for the intersection of @src1 and @src2, or NULL.
+ * @src1: a #GeglRectangle
+ * @src2: a #GeglRectangle
+ *
+ * Calculates the intersection of two rectangles. It is allows for dest to be the same
+ * as either @src1 or @src2. If the rectangles do not intersect, dest's width and height
+ * are set to 0 and its x and y values are undefined.
+ *
+ * Returns TRUE if the rectangles intersect.
+ */
 gboolean    gegl_rectangle_intersect     (GeglRectangle       *dest,
                                           const GeglRectangle *src1,
                                           const GeglRectangle *src2);
-gboolean    gegl_rectangle_contains      (const GeglRectangle *r,
-                                          const GeglRectangle *s);
+
+/**
+ * gegl_rectangle_contains:
+ * @parent: a #GeglRectangle
+ * @child: a #GeglRectangle
+ *
+ * Checks if the #GeglRectangle @child is fully contained within @parent.
+ *
+ * Returns TRUE if the @child is fully contained in @parent.
+ */
+gboolean    gegl_rectangle_contains      (const GeglRectangle *parent,
+                                          const GeglRectangle *child);
+
+
+
+/***
+ * Aligned memory:
+ *
+ * GEGL provides functions to allocate and free buffers that are guaranteed to
+ * be on 16 byte aligned memory addresses.
+ */
+
+/**
+ * gegl_malloc:
+ * @n_bytes: the number of bytes to allocte.
+ *
+ * Allocates @n_bytes of memory. If n_bytes is 0 it returns NULL.
+ *
+ * Returns a pointer to the allocated memory.
+ */
+gpointer gegl_malloc                  (gsize    n_bytes);
+
+/**
+ * gegl_free:
+ * @mem: the memory to free.
+ *
+ * Frees the memory pointed to by @mem, if @mem is NULL it will warn and abort.
+ */
+void     gegl_free                    (gpointer mem);
+
+
+/***
+ */
 
 GType       gegl_rectangle_get_type      (void) G_GNUC_CONST;
 
@@ -60,10 +186,9 @@
 gint        _gegl_float_epsilon_equal (float     v1,
                                        float     v2);
 
-gpointer gegl_malloc                  (gsize size);
-void     gegl_free                    (gpointer buf);
-
 
+/***
+ */
 
 G_END_DECLS
 

Modified: trunk/gegl/gegl.h.in
==============================================================================
--- trunk/gegl/gegl.h.in	(original)
+++ trunk/gegl/gegl.h.in	Fri Jan  2 02:31:02 2009
@@ -864,21 +864,7 @@
 
 
 #ifndef GEGL_INTERNAL
-/***
- * GeglRectangle:
- *
- * GeglRectangles are used in #gegl_node_get_bounding_box and #gegl_node_blit
- * for specifying rectangles.
- *
- * </p><pre>struct GeglRectangle
- * {
- *   gint x;
- *   gint y;
- *   gint width;
- *   gint height;
- * };</pre><p>
- *
- */
+
 struct _GeglRectangle
 {
   gint x;