Synopsis
#include <cpml-1/cpml.h> typedef CpmlVector; struct CpmlPair; void cpml_pair_from_cairo (CpmlPair *pair
,const cairo_path_data_t *path_data
); void cpml_pair_copy (CpmlPair *pair
,const CpmlPair *src
); int cpml_pair_equal (const CpmlPair *pair
,const CpmlPair *src
); void cpml_pair_transform (CpmlPair *pair
,const cairo_matrix_t *matrix
); double cpml_pair_squared_distance (const CpmlPair *from
,const CpmlPair *to
); double cpml_pair_distance (const CpmlPair *from
,const CpmlPair *to
); void cpml_pair_to_cairo (const CpmlPair *pair
,cairo_path_data_t *path_data
); void cpml_vector_from_angle (CpmlVector *vector
,double angle
); void cpml_vector_set_length (CpmlVector *vector
,double length
); double cpml_vector_angle (const CpmlVector *vector
); void cpml_vector_normal (CpmlVector *vector
); void cpml_vector_transform (CpmlVector *vector
,const cairo_matrix_t *matrix
);
Description
The CpmlPair is a generic 2D structure. It can be used to represent coordinates, sizes, offsets or whatever have two components.
The name comes from MetaFont.
Details
CpmlVector
typedef CpmlPair CpmlVector;
Another name for CpmlPair. It is used to clarify when a function expects a generic pair (usually coordinates) or a vector.
A vector represents a line starting from the origin (0,0) and ending to the given coordinates pair. Vectors are useful to define direction and length at once. Keep in mind the cairo default coordinates system is not problably what you expect: the x axis increases at right (as usual) but the y axis increases at down (the reverse of a usual cartesian plan). An angle of 0 is at V=(1; 0) (middle right).
Since 1.0
cpml_pair_from_cairo ()
void cpml_pair_from_cairo (CpmlPair *pair
,const cairo_path_data_t *path_data
);
Sets pair
from a cairo_path_data_t struct. path_data
should contains
a point data: it is up to the caller to be sure path_data
is valid.
|
the destination CpmlPair |
|
the original path data point. [allow-none][type gpointer] |
Since 1.0
cpml_pair_copy ()
void cpml_pair_copy (CpmlPair *pair
,const CpmlPair *src
);
Copies src
in pair
. If src
or pair
is NULL
, this function does
nothing.
Since 1.0
cpml_pair_equal ()
int cpml_pair_equal (const CpmlPair *pair
,const CpmlPair *src
);
Compares pair
to src
and returns 1 if the pairs are equals.
Two NULL
pairs are considered equal.
|
the first pair to compare. [allow-none] |
|
the second pair to compare. [allow-none] |
Returns : |
1 if pair is equal to src , 0 otherwise. [type gboolean]
|
Since 1.0
cpml_pair_transform ()
void cpml_pair_transform (CpmlPair *pair
,const cairo_matrix_t *matrix
);
Shortcut to apply a specific transformation matrix to pair
.
|
the destination CpmlPair struct |
|
the transformation matrix. [allow-none] |
Since 1.0
cpml_pair_squared_distance ()
double cpml_pair_squared_distance (const CpmlPair *from
,const CpmlPair *to
);
Gets the squared distance between from
and to
. This value is useful
for comparation purpose: if you need to get the real distance, use
cpml_pair_distance()
.
from
or to
could be NULL
, in which case the fallback (0, 0) pair
will be used.
|
the first CpmlPair struct. [allow-none] |
|
the second CpmlPair struct. [allow-none] |
Returns : |
the squared distance |
Since 1.0
cpml_pair_distance ()
double cpml_pair_distance (const CpmlPair *from
,const CpmlPair *to
);
Gets the distance between from
and to
. If you need this value only
for comparation purpose, you could use cpm_pair_squared_distance()
instead.
from
or to
could be NULL
, in which case the fallback (0, 0) pair
will be used.
The algorithm used is adapted from: "Replacing Square Roots by Pythagorean Sums" by Clave Moler and Donald Morrison (1983) IBM Journal of Research and Development 27 (6): 577–581 http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
|
the first CpmlPair struct. [allow-none] |
|
the second CpmlPair struct. [allow-none] |
Returns : |
the distance |
Since 1.0
cpml_pair_to_cairo ()
void cpml_pair_to_cairo (const CpmlPair *pair
,cairo_path_data_t *path_data
);
Sets a cairo_path_data_t struct to pair
. This is exactly the reverse
operation of cpml_pair_from_cairo()
.
|
the source CpmlPair |
|
the path data point to modify. [out][allow-none][type gpointer] |
Since 1.0
cpml_vector_from_angle ()
void cpml_vector_from_angle (CpmlVector *vector
,double angle
);
Calculates the coordinates of the point far 1
from the origin
in the angle
direction. The result is stored in vector
.
|
the destination CpmlVector |
|
angle of direction, in radians |
Since 1.0
cpml_vector_set_length ()
void cpml_vector_set_length (CpmlVector *vector
,double length
);
Imposes the specified length
to vector
. If the old length is 0
(and so the direction is not known), nothing happens. If length
is 0
, vector
is set to (0, 0).
The length
parameter can be negative, in which case the vector
is inverted.
|
a CpmlVector |
|
the new length |
Since 1.0
cpml_vector_angle ()
double cpml_vector_angle (const CpmlVector *vector
);
Gets the angle of vector
, in radians. If vector
is (0, 0),
0 is returned.
|
the source CpmlVector |
Returns : |
the angle in radians, a value between -M_PI and M_PI |
Since 1.0
cpml_vector_normal ()
void cpml_vector_normal (CpmlVector *vector
);
Stores in vector
a vector normal to the original vector
.
The length is retained.
The algorithm is really quick because no trigonometry is involved.
|
the subject CpmlVector |
Since 1.0
cpml_vector_transform ()
void cpml_vector_transform (CpmlVector *vector
,const cairo_matrix_t *matrix
);
Shortcut to apply a specific transformation matrix to vector
.
It works in a similar way of cpml_pair_transform()
but uses
cairo_matrix_transform_distance()
instead of
cairo_matrix_transform_point()
.
|
the destination CpmlPair struct |
|
the transformation matrix. [allow-none] |
Since 1.0