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


struct CpmlPair

struct CpmlPair {
    double  x, y;
};

A generic 2D structure.

double x;

the x component of the pair

double y;

the y component of the pair

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.

pair :

the destination CpmlPair

path_data :

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.

pair :

the destination CpmlPair

src :

the source CpmlPair. [allow-none]

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.

pair :

the first pair to compare. [allow-none]

src :

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.

pair :

the destination CpmlPair struct

matrix :

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.

from :

the first CpmlPair struct. [allow-none]

to :

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

from :

the first CpmlPair struct. [allow-none]

to :

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

pair :

the source CpmlPair

path_data :

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.

vector :

the destination CpmlVector

angle :

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.

vector :

a CpmlVector

length :

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.

vector :

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.

vector :

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

vector :

the destination CpmlPair struct

matrix :

the transformation matrix. [allow-none]

Since 1.0