1 /* CPML - Cairo Path Manipulation Library
2 * Copyright (C) 2008, 2009 Nicola Fontana <ntd at entidi.it>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
23 * @Section_Id:CpmlPair
25 * @short_description: Basic struct holding a couple of values
27 * The #CpmlPair is a generic 2D structure. It can be used to represent
28 * coordinates, sizes, offsets or whatever have two components.
30 * The name comes from MetaFont.
35 * @x: the x component of the pair
36 * @y: the y component of the pair
38 * A generic 2D structure.
43 * @x: the x component of the vector
44 * @y: the y component of the vector
46 * Another name for #CpmlPair. It is used to clarify when a function expects
49 * A vector represents a line starting from the origin (0,0) and ending
50 * to the given coordinates pair. Vectors are useful to define directions
51 * and length at once. Keep in mind the cairo default coordinates system
52 * is not problably what you expect: the x axis increases at right
53 * (as usual) but the y axis increases at down (the reverse of a usual
54 * cartesian plan). An angle of 0 is at V=(1; 0) (middle right).
58 #include "cpml-pair.h"
65 static CpmlPair fallback_pair
= { 0, 0 };
70 * @pair: the destination #CpmlPair
71 * @src: the source #CpmlPair
73 * Copies @src in @pair.
76 cpml_pair_copy(CpmlPair
*pair
, const CpmlPair
*src
)
78 memcpy(pair
, src
, sizeof(CpmlPair
));
82 * cpml_pair_from_cairo:
83 * @pair: the destination #CpmlPair
84 * @path_data: the original path data point
86 * Sets @pair from a #cairo_path_data_t struct. @path_data should contains
87 * a point data: it is up to the caller to be sure @path_data is valid.
90 cpml_pair_from_cairo(CpmlPair
*pair
, const cairo_path_data_t
*path_data
)
92 pair
->x
= path_data
->point
.x
;
93 pair
->y
= path_data
->point
.y
;
101 * Negates the coordinates of @pair.
104 cpml_pair_negate(CpmlPair
*pair
)
114 * Inverts (1/x) the coordinates of @pair. If @pair cannot be inverted
115 * because one coordinate is 0, 0 is returned and no transformation is
118 * Returns: 1 on success, 0 on errors
121 cpml_pair_invert(CpmlPair
*pair
)
123 if (pair
->x
== 0 || pair
->y
== 0)
126 pair
->x
= 1. / pair
->x
;
127 pair
->y
= 1. / pair
->y
;
133 * @pair: the destination #CpmlPair
134 * @src: the source pair to add
136 * Adds @src to @pair and stores the result in @pair. In other words,
137 * @pair = @pair + @src.
140 cpml_pair_add(CpmlPair
*pair
, const CpmlPair
*src
)
148 * @pair: the destination #CpmlPair
149 * @src: the source pair to subtract
151 * Subtracts @src from @pair and stores the result in @pair. In other words,
152 * @pair = @pair - @src.
155 cpml_pair_sub(CpmlPair
*pair
, const CpmlPair
*src
)
163 * @pair: the destination #CpmlPair
164 * @src: the source pair factor
166 * Multiplies the x coordinate of @pair by the @src x factor and the
167 * y coordinate by the @src y factor.
170 cpml_pair_mul(CpmlPair
*pair
, const CpmlPair
*src
)
178 * @pair: the destination #CpmlPair
179 * @src: the source pair divisor
181 * Divides the x coordinate of @pair by the @src x divisor and the
182 * y coordinate by the @src y divisor. If @pair cannot be divided
183 * because of a division by 0, 0 is returned and no transformation
186 * Returns: 1 on success, 0 on errors
189 cpml_pair_div(CpmlPair
*pair
, const CpmlPair
*src
)
191 if (src
->x
== 0 || src
->y
== 0)
200 * cpml_pair_transform:
201 * @pair: the destination #CpmlPair struct
202 * @matrix: the transformation matrix
204 * Shortcut to apply a specific transformation matrix to @pair.
207 cpml_pair_transform(CpmlPair
*pair
, const cairo_matrix_t
*matrix
)
209 cairo_matrix_transform_point(matrix
, &pair
->x
, &pair
->y
);
213 * cpml_pair_squared_distance:
214 * @from: the first #CpmlPair struct
215 * @to: the second #CpmlPair struct
217 * Gets the squared distance between @from and @to. This value is useful
218 * for comparation purpose: if you need to get the real distance, use
219 * cpml_pair_distance().
221 * @from or @to could be %NULL, in which case the fallback (0, 0) pair
224 * Returns: the squared distance
227 cpml_pair_squared_distance(const CpmlPair
*from
, const CpmlPair
*to
)
232 from
= &fallback_pair
;
239 return x
* x
+ y
* y
;
243 * cpml_pair_distance:
244 * @from: the first #CpmlPair struct
245 * @to: the second #CpmlPair struct
246 * @distance: where to store the result
248 * Gets the distance between @from and @to, storing the result in @distance.
249 * If you need this value only for comparation purpose, you could use
250 * cpm_pair_squared_distance() instead.
252 * @from or @to could be %NULL, in which case the fallback (0, 0) pair
255 * The algorithm used is adapted from:
256 * "Replacing Square Roots by Pythagorean Sums"
257 * by Clave Moler and Donald Morrison (1983)
258 * IBM Journal of Research and Development 27 (6): 577–581
259 * http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
261 * Returns: the distance
264 cpml_pair_distance(const CpmlPair
*from
, const CpmlPair
*to
)
270 from
= &fallback_pair
;
307 * cpml_pair_to_cairo:
308 * @pair: the destination #CpmlPair
309 * @path_data: the original path data point
311 * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
312 * operation of cpml_pair_from_cairo().
315 cpml_pair_to_cairo(const CpmlPair
*pair
, cairo_path_data_t
*path_data
)
317 path_data
->point
.x
= pair
->x
;
318 path_data
->point
.y
= pair
->y
;
323 * cpml_vector_from_angle:
324 * @vector: the destination #CpmlVector
325 * @angle: angle of direction, in radians
327 * Calculates the coordinates of the point far %1 from the origin
328 * in the @angle direction. The result is stored in @vector.
331 cpml_vector_from_angle(CpmlVector
*vector
, double angle
)
333 /* Check for common conditions */
334 if (angle
== -M_PI_2
) {
337 } else if (angle
== M_PI_2
) {
340 } else if (angle
== M_PI
|| angle
== -M_PI
) {
343 } else if (angle
== 0) {
347 vector
->x
= cos(angle
);
348 vector
->y
= sin(angle
);
353 * cpml_vector_set_length:
354 * @vector: a #CpmlVector
355 * @length: the new length
357 * Imposes the specified @length to @vector. If the old length is %0
358 * (and so the direction is not known), nothing happens. If @length
359 * is %0, @vector is set to (0, 0).
361 * The @length parameter can be negative, in which case the vector
365 cpml_vector_set_length(CpmlVector
*vector
, double length
)
375 divisor
= cpml_pair_distance(NULL
, vector
);
377 /* Check for valid length (anything other than 0) */
380 vector
->x
/= divisor
;
381 vector
->y
/= divisor
;
387 * @vector: the source #CpmlVector
389 * Gets the angle of @vector, in radians. If @vector is (0, 0),
392 * Returns: the angle in radians, a value between -M_PI and M_PI
395 cpml_vector_angle(const CpmlVector
*vector
)
397 /* Check for common conditions */
399 return vector
->x
>= 0 ? 0 : M_PI
;
401 return vector
->y
> 0 ? M_PI_2
: -M_PI_2
;
402 if (vector
->x
== vector
->y
)
403 return vector
->x
> 0 ? M_PI_4
: -M_PI_4
* 3;
404 if (vector
->x
== -vector
->y
)
405 return vector
->x
> 0 ? -M_PI_4
: M_PI_4
* 3;
407 return atan2(vector
->y
, vector
->x
);
411 * cpml_vector_normal:
412 * @vector: the subject #CpmlVector
414 * Stores in @vector a vector normal to the original @vector.
415 * The length is retained.
417 * The algorithm is really quick because no trigonometry is involved.
420 cpml_vector_normal(CpmlVector
*vector
)
422 double tmp
= vector
->x
;
424 vector
->x
= -vector
->y
;
429 * cpml_vector_transform:
430 * @vector: the destination #CpmlPair struct
431 * @matrix: the transformation matrix
433 * Shortcut to apply a specific transformation matrix to @vector.
434 * It works in a similar way of cpml_pair_transform() but uses
435 * cairo_matrix_transform_distance() instead of
436 * cairo_matrix_transform_point().
439 cpml_vector_transform(CpmlPair
*vector
, const cairo_matrix_t
*matrix
)
441 cairo_matrix_transform_distance(matrix
, &vector
->x
, &vector
->y
);