From 2ce4075eebe146aff4ea9f77faf80d408a2d64aa Mon Sep 17 00:00:00 2001 From: Michael Natterer Date: Fri, 2 Jul 2010 14:41:35 +0200 Subject: [PATCH] libgimpmath: move docs from template files to inline comments --- devel-docs/libgimpmath/.gitignore | 1 + devel-docs/libgimpmath/tmpl/.gitignore | 2 - devel-docs/libgimpmath/tmpl/gimpmath.sgml | 78 ---- devel-docs/libgimpmath/tmpl/gimpmatrix.sgml | 268 ----------- devel-docs/libgimpmath/tmpl/gimpmd5.sgml | 29 -- devel-docs/libgimpmath/tmpl/gimpvector.sgml | 482 -------------------- libgimpmath/gimpmath.h | 65 ++- libgimpmath/gimpmatrix.c | 18 + libgimpmath/gimpmatrix.h | 18 + libgimpmath/gimpmd5.c | 9 + libgimpmath/gimpvector.c | 10 + libgimpmath/gimpvector.h | 24 + 12 files changed, 136 insertions(+), 868 deletions(-) delete mode 100644 devel-docs/libgimpmath/tmpl/.gitignore delete mode 100644 devel-docs/libgimpmath/tmpl/gimpmath.sgml delete mode 100644 devel-docs/libgimpmath/tmpl/gimpmatrix.sgml delete mode 100644 devel-docs/libgimpmath/tmpl/gimpmd5.sgml delete mode 100644 devel-docs/libgimpmath/tmpl/gimpvector.sgml diff --git a/devel-docs/libgimpmath/.gitignore b/devel-docs/libgimpmath/.gitignore index fbb7295080..6bf158555b 100644 --- a/devel-docs/libgimpmath/.gitignore +++ b/devel-docs/libgimpmath/.gitignore @@ -12,6 +12,7 @@ /libgimpmath-undeclared.txt /libgimpmath-undocumented.txt /html +/tmpl /xml /version /.libs diff --git a/devel-docs/libgimpmath/tmpl/.gitignore b/devel-docs/libgimpmath/tmpl/.gitignore deleted file mode 100644 index 8cddcbc231..0000000000 --- a/devel-docs/libgimpmath/tmpl/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -/libgimpmath-unused.sgml -/*.bak diff --git a/devel-docs/libgimpmath/tmpl/gimpmath.sgml b/devel-docs/libgimpmath/tmpl/gimpmath.sgml deleted file mode 100644 index 987eb3b96b..0000000000 --- a/devel-docs/libgimpmath/tmpl/gimpmath.sgml +++ /dev/null @@ -1,78 +0,0 @@ - -GimpMath - - -Mathematical definitions and macros. - - - -Mathematical definitions and macros. These macros should be used -rather than the ones from math.h for enhanced portability. - - - - - - - - - - - - -This macro rounds its argument @x to an integer value in floating point -format. - - -@x: the value to be rounded. - - - - -This macro rounds its argument @x to the nearest integer. - - -@x: the value to be rounded. - - - - -This macro squares its argument @x. - - -@x: the value to be squared. - - - - -This macro limits it argument @a, an (0-511) int, to 255. - - -@a: the value to be limited. - - - - -This macro clamps its argument @a, an int32-range int, between 0 and -255 inclusive. - - -@a: the value to be clamped. - - - - -This macro converts its argument @angle from degree to radian. - - -@angle: the angle to be converted. - - - - -This macro converts its argument @angle from radian to degree. - - -@angle: the angle to be converted. - - diff --git a/devel-docs/libgimpmath/tmpl/gimpmatrix.sgml b/devel-docs/libgimpmath/tmpl/gimpmatrix.sgml deleted file mode 100644 index 07871287a1..0000000000 --- a/devel-docs/libgimpmath/tmpl/gimpmatrix.sgml +++ /dev/null @@ -1,268 +0,0 @@ - -GimpMatrix - - -Utilities to set up and manipulate 3x3 transformation matrices. - - - -When doing image manipulation you will often need 3x3 transformation -matrices that define translation, rotation, scaling, shearing and -arbitrary perspective transformations using a 3x3 matrix. Here you'll -find a set of utility functions to set up those matrices and to perform -basic matrix manipulations and tests. - - -Each matrix class has a 2 dimensional gdouble coeff member. The -element for row r and column c of the matrix is coeff[r][c]. - - - - -#GimpVector2 - - -#GimpVector3 - - -#GimpVector4 - - - - - - - -A two by two matrix. - - -@coeff: - - - -A three by three matrix. - - -@coeff: - - - -A four by four matrix. - - -@coeff: - - - - - - -@matrix: - - - - - - - -@matrix1: -@matrix2: - - - - - - - -@matrix: - - - - - - - -@matrix1: -@matrix2: - - - - - - - -@matrix: -@x: -@y: - - - - - - - -@matrix: -@x: -@y: - - - - - - - -@matrix: -@theta: - - - - - - - -@matrix: -@amount: - - - - - - - -@matrix: -@amount: - - - - - - - -@matrix: -@a: -@b: -@c: -@d: -@e: -@f: - - - - - - - -@matrix: -@x: -@y: -@newx: -@newy: - - - - - - - -@matrix: -@Returns: - - - - - - - -@matrix: - - - - - - - -@matrix: -@Returns: - - - - - - - -@matrix: -@Returns: - - - - - - - -@matrix: -@Returns: - - - - - - - -@matrix: -@Returns: - - - - - - - -@matrix: -@a: -@b: -@c: - - - - - - - - - - - - - - - - - - - - - -@pspec: - - - - - - - -@name: -@nick: -@blurb: -@default_value: -@flags: -@Returns: - - - - - - - -@value: - - diff --git a/devel-docs/libgimpmath/tmpl/gimpmd5.sgml b/devel-docs/libgimpmath/tmpl/gimpmd5.sgml deleted file mode 100644 index 43308dcf46..0000000000 --- a/devel-docs/libgimpmath/tmpl/gimpmd5.sgml +++ /dev/null @@ -1,29 +0,0 @@ - -GimpMD5 - - -the MD5 message-digest algorithm - - - - - - - - - - - - - - - - - - - -@buffer: -@buffer_size: -@digest: - - diff --git a/devel-docs/libgimpmath/tmpl/gimpvector.sgml b/devel-docs/libgimpmath/tmpl/gimpvector.sgml deleted file mode 100644 index 4bbfa48518..0000000000 --- a/devel-docs/libgimpmath/tmpl/gimpvector.sgml +++ /dev/null @@ -1,482 +0,0 @@ - -GimpVector - - -Utilities to set up and manipulate vectors. - - - -Utilities to set up and manipulate vectors. - - - - - -#GimpMatrix3 - - -#GimpMatrix4 - - - - - - - -A two dimensional vector. - - -@x: -@y: - - - -A three dimensional vector. - - -@x: -@y: -@z: - - - -A four dimensional vector. - - -@x: -@y: -@z: -@w: - - - - - - -@x: -@y: -@Returns: - - - - - - - -@vector: -@x: -@y: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: -@factor: - - - - - - - -@vector: -@factor: -@Returns: - - - - - - - -@vector: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: - - - - - - - -@vector: -@Returns: - - - - - - - -@result: -@vector1: -@vector2: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@result: -@vector1: -@vector2: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector: -@alpha: - - - - - - - -@vector: -@alpha: -@Returns: - - - - - - - -@x: -@y: -@z: -@Returns: - - - - - - - -@vector: -@x: -@y: -@z: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: -@factor: - - - - - - - -@vector: -@factor: -@Returns: - - - - - - - -@vector: - - - - - - - -@vector: -@Returns: - - - - - - - -@vector: - - - - - - - -@vector: -@Returns: - - - - - - - -@result: -@vector1: -@vector2: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@result: -@vector1: -@vector2: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector1: -@vector2: -@Returns: - - - - - - - -@vector: -@alpha: -@beta: -@gamma: - - - - - - - -@vector: -@alpha: -@beta: -@gamma: -@Returns: - - - - - - - -@sx: -@sy: -@w: -@h: -@x: -@y: -@vp: -@p: - - - - - - - -@sx: -@sy: -@w: -@h: -@x: -@y: -@vp: -@p: -@Returns: - - - - - - - -@sx: -@sy: -@w: -@h: -@x: -@y: -@vp: -@p: - - diff --git a/libgimpmath/gimpmath.h b/libgimpmath/gimpmath.h index d9faa36599..ac77dcc9c7 100644 --- a/libgimpmath/gimpmath.h +++ b/libgimpmath/gimpmath.h @@ -39,31 +39,78 @@ G_BEGIN_DECLS -/* Some portability enhancing stuff. For use both by the gimp app - * as well as plug-ins and modules. - * - * Include this instead of just . - */ -/* Use RINT() instead of rint() */ +/** + * SECTION: gimpmath + * @title: GimpMath + * @short_description: Mathematical definitions and macros. + * + * Mathematical definitions and macros for use both by the GIMP + * application and plug-ins. These macros should be used rather than + * the ones from for enhanced portability. + **/ + + +/** + * RINT: + * @x: the value to be rounded + * + * This macro rounds its argument @x to an integer value in floating + * point format. Use RINT() instead of rint(). + **/ #ifdef HAVE_RINT #define RINT(x) rint(x) #else #define RINT(x) floor ((x) + 0.5) #endif +/** + * ROUND: + * @x: the value to be rounded. + * + * This macro rounds its argument @x to the nearest integer. + **/ #define ROUND(x) ((int) ((x) + 0.5)) -/* Square */ +/** + * SQR: + * @x: the value to be squared. + * + * This macro squares its argument @x. + **/ #define SQR(x) ((x) * (x)) -/* Limit a (0->511) int to 255 */ +/** + * MAX255: + * @a: the value to be limited. + * + * This macro limits it argument @a, an (0-511) int, to 255. + **/ #define MAX255(a) ((a) | (((a) & 256) - (((a) & 256) >> 8))) -/* Clamp a >>int32<<-range int between 0 and 255 inclusive */ +/** + * CLAMP0255: + * @a: the value to be clamped. + * + * This macro clamps its argument @a, an int32-range int, between 0 + * and 255 inclusive. + **/ #define CLAMP0255(a) CLAMP(a,0,255) +/** + * gimp_deg_to_rad: + * @angle: the angle to be converted. + * + * This macro converts its argument @angle from degree to radian. + **/ #define gimp_deg_to_rad(angle) ((angle) * (2.0 * G_PI) / 360.0) + +/** + * gimp_rad_to_deg: + * @angle: the angle to be converted. + * + * This macro converts its argument @angle from radian to degree. + **/ #define gimp_rad_to_deg(angle) ((angle) * 360.0 / (2.0 * G_PI)) diff --git a/libgimpmath/gimpmatrix.c b/libgimpmath/gimpmatrix.c index 4114eaf366..5d09a31544 100644 --- a/libgimpmath/gimpmatrix.c +++ b/libgimpmath/gimpmatrix.c @@ -26,6 +26,24 @@ #include "gimpmath.h" +/** + * SECTION: gimpmatrix + * @title: GimpMatrix + * @short_description: Utilities to set up and manipulate 3x3 + * transformation matrices. + * @see_also: #GimpVector2, #GimpVector3, #GimpVector4 + * + * When doing image manipulation you will often need 3x3 + * transformation matrices that define translation, rotation, scaling, + * shearing and arbitrary perspective transformations using a 3x3 + * matrix. Here you'll find a set of utility functions to set up those + * matrices and to perform basic matrix manipulations and tests. + * + * Each matrix class has a 2 dimensional gdouble coeff member. The + * element for row r and column c of the matrix is coeff[r][c]. + **/ + + #define EPSILON 1e-6 diff --git a/libgimpmath/gimpmatrix.h b/libgimpmath/gimpmatrix.h index 5919b665a3..c55646ccc6 100644 --- a/libgimpmath/gimpmatrix.h +++ b/libgimpmath/gimpmatrix.h @@ -26,16 +26,34 @@ G_BEGIN_DECLS /* For information look into the C source or the html documentation */ +/** + * GimpMatrix2 + * @coeff: the coefficients + * + * A two by two matrix. + **/ struct _GimpMatrix2 { gdouble coeff[2][2]; }; +/** + * GimpMatrix3 + * @coeff: the coefficients + * + * A three by three matrix. + **/ struct _GimpMatrix3 { gdouble coeff[3][3]; }; +/** + * GimpMatrix4 + * @coeff: the coefficients + * + * A four by four matrix. + **/ struct _GimpMatrix4 { gdouble coeff[4][4]; diff --git a/libgimpmath/gimpmd5.c b/libgimpmath/gimpmd5.c index 911f14d5e3..e3148847a3 100644 --- a/libgimpmath/gimpmd5.c +++ b/libgimpmath/gimpmd5.c @@ -13,6 +13,15 @@ #include "gimpmd5.h" +/** + * SECTION: gimpmd5 + * @title: GimpMD5 + * @short_description: The MD5 message-digest algorithm + * + * The MD5 message-digest algorithm + **/ + + /** * gimp_md5_get_digest: * @buffer: byte buffer diff --git a/libgimpmath/gimpvector.c b/libgimpmath/gimpvector.c index c963ea7a11..97bf70dc97 100644 --- a/libgimpmath/gimpvector.c +++ b/libgimpmath/gimpvector.c @@ -33,6 +33,16 @@ #include "gimpmath.h" +/** + * SECTION: gimpvector + * @title: GimpVector + * @short_description: Utilities to set up and manipulate vectors. + * @see_also: #GimpMatrix2, #GimpMatrix3, #GimpMatrix4 + * + * Utilities to set up and manipulate vectors. + **/ + + /*************************/ /* Some useful constants */ /*************************/ diff --git a/libgimpmath/gimpvector.h b/libgimpmath/gimpvector.h index 4ec383b7be..b3f56fe523 100644 --- a/libgimpmath/gimpvector.h +++ b/libgimpmath/gimpvector.h @@ -29,16 +29,40 @@ G_BEGIN_DECLS /* For information look into the C source or the html documentation */ +/** + * GimpVector2: + * @x: the x axis + * @y: the y axis + * + * A two dimensional vector. + **/ struct _GimpVector2 { gdouble x, y; }; +/** + * GimpVector3: + * @x: the x axis + * @y: the y axis + * @z: the z axis + * + * A three dimensional vector. + **/ struct _GimpVector3 { gdouble x, y, z; }; +/** + * GimpVector4: + * @x: the x axis + * @y: the y axis + * @z: the z axis + * @w: the w axis + * + * A four dimensional vector. + **/ struct _GimpVector4 { gdouble x, y, z, w;