CpmlPair

CpmlPair

typedef struct {
    double  x, y;
} CpmlPair;

A generic 2D structure.

CpmlVector

typedef struct _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).

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.

cpml_pair_copy ()

void                cpml_pair_copy                      (CpmlPair *pair,
                                                         const CpmlPair *src);

Copies src in pair.

cpml_pair_transform ()

void                cpml_pair_transform                 (CpmlPair *pair,
                                                         const cairo_matrix_t *matrix);

Shortcut to apply a specific transformation matrix to pair.

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.

cpml_pair_distance ()

double              cpml_pair_distance                  (const CpmlPair *from,
                                                         const CpmlPair *to);

Gets the distance between from and to, storing the result in distance. 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

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().

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.

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.

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.

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.

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().