[cairo-commit] cairo/src cairo.c, 1.47, 1.48 cairo.h, 1.68, 1.69 cairo_matrix.c, 1.15, 1.16

Thu Jan 27 11:35:28 PST 2005

Committed by: otaylor

Update of /cvs/cairo/cairo/src
In directory gabe:/tmp/cvs-serv29685/src

Modified Files:
	cairo.c cairo.h cairo_matrix.c 
Log Message:
2005-01-27  Owen Taylor  <otaylor at redhat.com>

        * configure.in Makefile.am docs/Makefile.am docs/public/*:
        Add framework for doing docs via gtk-doc.

        * src/cairo.[ch] src/cairo-matrix.c: Add some inline docs
        for arcs and matrices.

        * gtk-doc.m4 acinclude.m4: Check in files from gtk-doc
        to make the dependency on gtk-doc optional.

        * autogen.sh (LANG): Add --enable-gtk-doc to the default
        args.


Index: cairo.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.c,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -d -r1.47 -r1.48

--- cairo.c	20 Jan 2005 16:28:54 -0000	1.47
+++ cairo.c	27 Jan 2005 19:35:26 -0000	1.48
@@ -569,6 +569,39 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_arc:
+ * @cr: a Cairo context
+ * @xc: X position of the center of the arc
+ * @yc: Y position of the center of the arc
+ * @radius: the radius of the arc
+ * @angle1: the start angle, in radians
+ * @angle2: the end angle, in radians
+ * 
+ * Adds an arc from @angle1 to @angle2 to the current path. If there
+ * is a current point, that point is connected to the start of the arc
+ * by a straight line segment. Angles are measured in radians with an
+ * angle of 0 along the X axis and an angle of %M_PI radians (90
+ * degrees) along the Y axis, so with the default transformation
+ * matrix, positive angles are clockwise. (To convert from degrees to
+ * radians, use <literal>degrees * (M_PI / 180.)</literal>.)  This
+ * function gives the arc in the direction of increasing angle; see
+ * cairo_arc_negative() to get the arc in the direction of decreasing
+ * angle.
+ *
+ * A full arc is drawn as a circle. To make an oval arc, you can scale
+ * the current transformation matrix by different amounts in the X and
+ * Y directions. For example, to draw a full oval in the box given
+ * by @x, @y, @width, @height:
+ 
+ * <informalexample><programlisting>
+ * cairo_save (cr);
+ * cairo_translate (x + width / 2., y + height / 2.);
+ * cairo_scale (1. / (height / 2.), 1. / (width / 2.));
+ * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
+ * cairo_restore (cr);
+ * </programlisting></informalexample>
+ **/
 void
 cairo_arc (cairo_t *cr,
 	   double xc, double yc,
@@ -586,6 +619,20 @@
     CAIRO_CHECK_SANITY (cr);
 }
 
+/**
+ * cairo_arc_negative:
+ * @cr: a Cairo context
+ * @xc: X position of the center of the arc
+ * @yc: Y position of the center of the arc
+ * @radius: the radius of the arc
+ * @angle1: the start angle, in radians
+ * @angle2: the end angle, in radians
+ * 
+ * Adds an arc from @angle1 to @angle2 to the current path. The
+ * function behaves identically to cairo_arc() except that instead of
+ * giving the arc in the direction of increasing angle, it gives
+ * the arc in the direction of decreasing angle.
+ **/
 void
 cairo_arc_negative (cairo_t *cr,
 		    double xc, double yc,

Index: cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.68
retrieving revision 1.69
diff -u -d -r1.68 -r1.69
--- cairo.h	21 Jan 2005 22:33:48 -0000	1.68
+++ cairo.h	27 Jan 2005 19:35:26 -0000	1.69
@@ -50,8 +50,23 @@
 
 CAIRO_BEGIN_DECLS
 
+/**
+ * cairo_t
+ *
+ * A #cairo_t contains the current state of the rendering device,
+ * including coordinates of yet to be drawn shapes.
+ **/
 typedef struct _cairo cairo_t;
+
 typedef struct _cairo_surface cairo_surface_t;
+
+/**
+ * cairo_t
+ *
+ * A <structname>cairo_matrix</structname> holds an affine
+ * transformation, such as a scale, rotation, or shear, or a
+ * combination of those.
+ **/
 typedef struct _cairo_matrix cairo_matrix_t;
 typedef struct _cairo_pattern cairo_pattern_t;
 
@@ -166,6 +181,15 @@
 void
 cairo_set_line_width (cairo_t *cr, double width);
 
+
+/**
+ * cairo_line_cap_t
+ * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point
+ * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point
+ * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point
+ *
+ * enumeration for style of line-endings
+ **/
 typedef enum cairo_line_cap {
     CAIRO_LINE_CAP_BUTT,
     CAIRO_LINE_CAP_ROUND,
@@ -676,7 +700,7 @@
 cairo_matrix_set_identity (cairo_matrix_t *matrix);
 
 cairo_status_t
-cairo_matrix_set_affine (cairo_matrix_t *cr,
+cairo_matrix_set_affine (cairo_matrix_t *matrix,
 			 double a, double b,
 			 double c, double d,
 			 double tx, double ty);

Index: cairo_matrix.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo_matrix.c,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- cairo_matrix.c	19 Jan 2005 20:12:42 -0000	1.15
+++ cairo_matrix.c	27 Jan 2005 19:35:26 -0000	1.16
@@ -54,6 +54,14 @@
 static void
 _cairo_matrix_compute_adjoint (cairo_matrix_t *matrix);
 
+/**
+ * cairo_matrix_create:
+ * 
+ * Creates a new identity matrix.
+ * 
+ * Return value: a newly created matrix; free with cairo_matrix_destroy(),
+ *  or %NULL if memory couldn't be allocated.
+ **/
 cairo_matrix_t *
 cairo_matrix_create (void)
 {
@@ -80,6 +88,12 @@
     /* nothing to do here */
 }
 
+/**
+ * cairo_matrix_destroy:
+ * @matrix: a #cairo_matrix_t
+ * 
+ * Frees a matrix created with cairo_matrix_create.
+ **/
 void
 cairo_matrix_destroy (cairo_matrix_t *matrix)
 {
@@ -87,6 +101,15 @@
     free (matrix);
 }
 
+/**
+ * cairo_matrix_copy:
+ * @matrix: a #cairo_matrix_t
+ * @other: another #cairo_
+ * 
+ * Modifies @matrix to be identical to @other.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_copy (cairo_matrix_t *matrix, const cairo_matrix_t *other)
 {
@@ -96,6 +119,14 @@
 }
 slim_hidden_def(cairo_matrix_copy);
 
+/**
+ * cairo_matrix_set_identity:
+ * @matrix: a #cairo_matrix_t
+ * 
+ * Modifies @matrix to be an identity transformation.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_set_identity (cairo_matrix_t *matrix)
 {
@@ -105,6 +136,26 @@
 }
 slim_hidden_def(cairo_matrix_set_identity);
 
+/**
+ * cairo_matrix_set_affine:
+ * @matrix: a cairo_matrix_t
+ * @a: a component of the affine transformation
+ * @b: b component of the affine transformation
+ * @c: c component of the affine transformation
+ * @d: d component of the affine transformation
+ * @tx: X translation component of the affine transformation
+ * @ty: Y translation component of the affine transformation
+ * 
+ * Sets @matrix to be the affine transformation given by
+ * @a, b, @c, @d, @tx, @ty. The transformation is given
+ * by:
+ * <programlisting>
+ *  x_new = x * a + y * c + tx;
+ *  y_new = x * b + y * d + ty;
+ * </programlisting>
+ *
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_set_affine (cairo_matrix_t *matrix,
 			 double a, double b,
@@ -119,6 +170,21 @@
 }
 slim_hidden_def(cairo_matrix_set_affine);
 
+/**
+ * cairo_matrix_get_affine:
+ * @matrix: a @cairo_matrix_t
+ * @a: location to store a component of affine transformation, or %NULL
+ * @b: location to store b component of affine transformation, or %NULL
+ * @c: location to store c component of affine transformation, or %NULL
+ * @d: location to store d component of affine transformation, or %NULL
+ * @tx: location to store X-translation component of affine transformation, or %NULL
+ * @ty: location to store Y-translation component of affine transformation, or %NULL
+ * 
+ * Gets the matrix values for the affine tranformation that @matrix represents.
+ * See cairo_matrix_set_affine().
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_get_affine (cairo_matrix_t *matrix,
 			 double *a, double *b,
@@ -153,6 +219,18 @@
 				    tx, ty);
 }
 
+/**
+ * cairo_matrix_translate:
+ * @matrix: a cairo_matrix_t
+ * @tx: amount to rotate in the X direction
+ * @ty: amount to rotate in the Y direction
+ * 
+ * Applies a translation by @tx, @ty to the transformation in
+ * @matrix. The new transformation is given by first translating by
+ * @tx, @ty then applying the original transformation
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty)
 {
@@ -173,6 +251,18 @@
 				    0, 0);
 }
 
+/**
+ * cairo_matrix_scale:
+ * @matrix: a #cairo_matrix_t
+ * @sx: Scale factor in the X direction
+ * @sy: Scale factor in the Y direction
+ * 
+ * Applies scaling by @tx, @ty to the transformation in
+ * @matrix. The new transformation is given by first scaling by @sx
+ * and @sy then applying the original transformation
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy)
 {
@@ -202,6 +292,21 @@
 				    0, 0);
 }
 
+/**
+ * cairo_matrix_rotate:
+ * @matrix: a @cairo_matrix_t
+ * @radians: angle of rotation, in radians. Angles are defined
+ *  so that an angle of 90 degrees (%M_PI radians) rotates the
+ *  positive X axis into the positive Y axis. With the default
+ *  Cairo choice of axis orientation, positive rotations are
+ *  clockwise.
+ * 
+ * Applies rotation by @radians to the transformation in
+ * @matrix. The new transformation is given by first rotating by
+ * @radians then applying the original transformation
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_rotate (cairo_matrix_t *matrix, double radians)
 {
@@ -212,6 +317,19 @@
     return cairo_matrix_multiply (matrix, &tmp, matrix);
 }
 
+/**
+ * cairo_matrix_multiply:
+ * @result: a @cairo_matrix_t in which to store the result
+ * @a: a @cairo_matrix_t
+ * @b: a @cairo_matrix_t
+ * 
+ * Multiplies the affine transformations in @a and @b together
+ * and stores the result in @result. The resulting transformation
+ * is given by first applying the transformation in @b then
+ * applying the transformation in @a.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_multiply (cairo_matrix_t *result, const cairo_matrix_t *a, const cairo_matrix_t *b)
 {
@@ -238,6 +356,27 @@
 }
 slim_hidden_def(cairo_matrix_multiply);
 
+/**
+ * cairo_matrix_transform_distance:
+ * @matrix: a @cairo_matrix_t
+ * @dx: a distance in the X direction. An in/out parameter
+ * @dy: a distance in the Y direction. An in/out parameter
+ * 
+ * Transforms the vector (@dx, at dy) by @matrix.  Translation is
+ * ignored. In terms of the components of the affine transformation:
+ *
+ * <programlisting>
+ * dx2 = dx1 * a + dy1 * c;
+ * dy2 = dx1 * b + dy1 * d;
+ * </programlisting>
+ *
+ * Affine transformations are position invariant, so the same vector
+ * always transforms to the same vector. If (@x1, at y1) transforms
+ * to (@x2, at y2) then (@x1+ at dx1, at y1+@dy1) will transform to
+ * (@x1+ at dx2, at y1+@dy2) for all values of @x1 and @x2.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy)
 {
@@ -255,6 +394,16 @@
 }
 slim_hidden_def(cairo_matrix_transform_distance);
 
+/**
+ * cairo_matrix_transform_point:
+ * @matrix: a @cairo_matrix_t
+ * @x: X position. An in/out parameter
+ * @y: Y position. An in/out parameter
+ * 
+ * Transforms the point (@x, @y) by @matrix.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS, always.
+ **/
 cairo_status_t
 cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y)
 {
@@ -351,6 +500,19 @@
 			     c*ty - d*tx, b*tx - a*ty);
 }
 
+/**
+ * cairo_matrix_invert:
+ * @matrix: a @cairo_matrix_t
+ * 
+ * Changes @matrix to be the inverse of it's original value. Not
+ * all transformation matrices have inverses; if the matrix
+ * collapses points together (it is <firstterm>degenerate</firstterm>),
+ * then it has no inverse and this function will fail.
+ * 
+ * Returns: If @matrix has an inverse, modifies @matrix to
+ *  be the inverse matrix and returns %CAIRO_STATUS_SUCCESS. Otherwise,
+ *  returns %CAIRO_STATUS_INVALID_MATRIX.
+ **/
 cairo_status_t
 cairo_matrix_invert (cairo_matrix_t *matrix)
 {


