cpml/cpml-pair.c

   1 /* CPML - Cairo Path Manipulation Library
   2  * Copyright (C) 2008, 2009  Nicola Fontana <ntd at entidi.it>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20
  21 /**
  22  * SECTION:cpml-pair
  23  * @Section_Id:CpmlPair
  24  * @title: CpmlPair
  25  * @short_description: Basic struct holding a couple of values
  26  *
  27  * The #CpmlPair is a generic 2D structure. It can be used to represent
  28  * coordinates, sizes, offsets or whatever have two components.
  29  *
  30  * The name comes from MetaFont.
  31  **/
  32
  33 /**
  34  * CpmlPair:
  35  * @x: the x component of the pair
  36  * @y: the y component of the pair
  37  *
  38  * A generic 2D structure.
  39  **/
  40
  41 /**
  42  * CpmlVector:
  43  * @x: the x component of the vector
  44  * @y: the y component of the vector
  45  *
  46  * Another name for #CpmlPair. It is used to clarify when a function expects
  47  * a pair or a vector.
  48  *
  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).
  55  **/
  56
  57
  58 #include "cpml-internal.h"
  59 #include <stdlib.h>
  60 #include <string.h>
  61 #include <math.h>
  62
  63
  64 static CpmlPair fallback_pair = { 0, 0 };
  65
  66
  67 /**
  68  * cpml_pair_copy:
  69  * @pair: the destination #CpmlPair
  70  * @src: the source #CpmlPair
  71  *
  72  * Copies @src in @pair.
  73  **/
  74 void
  75 cpml_pair_copy(CpmlPair *pair, const CpmlPair *src)
  76 {
  77     memcpy(pair, src, sizeof(CpmlPair));
  78 }
  79
  80 /**
  81  * cpml_pair_from_cairo:
  82  * @pair: the destination #CpmlPair
  83  * @path_data: the original path data point
  84  *
  85  * Sets @pair from a #cairo_path_data_t struct. @path_data should contains
  86  * a point data: it is up to the caller to be sure @path_data is valid.
  87  **/
  88 void
  89 cpml_pair_from_cairo(CpmlPair *pair, const cairo_path_data_t *path_data)
  90 {
  91     pair->x = path_data->point.x;
  92     pair->y = path_data->point.y;
  93 }
  94
  95
  96 /**
  97  * cpml_pair_negate:
  98  * @pair: a #CpmlPair
  99  *
 100  * Negates the coordinates of @pair.
 101  **/
 102 void
 103 cpml_pair_negate(CpmlPair *pair)
 104 {
 105     pair->x = - pair->x;
 106     pair->y = - pair->y;
 107 }
 108
 109 /**
 110  * cpml_pair_invert:
 111  * @pair: a #CpmlPair
 112  *
 113  * Inverts (1/x) the coordinates of @pair. If @pair cannot be inverted
 114  * because one coordinate is 0, 0 is returned and no transformation is
 115  * performed.
 116  *
 117  * Returns: 1 on success, 0 on errors
 118  **/
 119 cairo_bool_t
 120 cpml_pair_invert(CpmlPair *pair)
 121 {
 122     if (pair->x == 0 || pair->y == 0)
 123         return 0;
 124
 125     pair->x = 1. / pair->x;
 126     pair->y = 1. / pair->y;
 127     return 1;
 128 }
 129
 130 /**
 131  * cpml_pair_add:
 132  * @pair: the destination #CpmlPair
 133  * @src:  the source pair to add
 134  *
 135  * Adds @src to @pair and stores the result in @pair. In other words,
 136  * @pair = @pair + @src.
 137  **/
 138 void
 139 cpml_pair_add(CpmlPair *pair, const CpmlPair *src)
 140 {
 141     pair->x += src->x;
 142     pair->y += src->y;
 143 }
 144
 145 /**
 146  * cpml_pair_sub:
 147  * @pair: the destination #CpmlPair
 148  * @src:  the source pair to subtract
 149  *
 150  * Subtracts @src from @pair and stores the result in @pair. In other words,
 151  * @pair = @pair - @src.
 152  **/
 153 void
 154 cpml_pair_sub(CpmlPair *pair, const CpmlPair *src)
 155 {
 156     pair->x -= src->x;
 157     pair->y -= src->y;
 158 }
 159
 160 /**
 161  * cpml_pair_mul:
 162  * @pair: the destination #CpmlPair
 163  * @src:  the source pair factor
 164  *
 165  * Multiplies the x coordinate of @pair by the @src x factor and the
 166  * y coordinate by the @src y factor.
 167  **/
 168 void
 169 cpml_pair_mul(CpmlPair *pair, const CpmlPair *src)
 170 {
 171     pair->x *= src->x;
 172     pair->y *= src->y;
 173 }
 174
 175 /**
 176  * cpml_pair_div:
 177  * @pair: the destination #CpmlPair
 178  * @src:  the source pair divisor
 179  *
 180  * Divides the x coordinate of @pair by the @src x divisor and the
 181  * y coordinate by the @src y divisor. If @pair cannot be divided
 182  * because of a division by 0, 0 is returned and no transformation
 183  * is performed.
 184  *
 185  * Returns: 1 on success, 0 on errors
 186  **/
 187 cairo_bool_t
 188 cpml_pair_div(CpmlPair *pair, const CpmlPair *src)
 189 {
 190     if (src->x == 0 || src->y == 0)
 191         return 0;
 192
 193     pair->x /= src->x;
 194     pair->y /= src->y;
 195     return 1;
 196 }
 197
 198 /**
 199  * cpml_pair_transform:
 200  * @pair: the destination #CpmlPair struct
 201  * @matrix: the transformation matrix
 202  *
 203  * Shortcut to apply a specific transformation matrix to @pair.
 204  **/
 205 void
 206 cpml_pair_transform(CpmlPair *pair, const cairo_matrix_t *matrix)
 207 {
 208     cairo_matrix_transform_point(matrix, &pair->x, &pair->y);
 209 }
 210
 211 /**
 212  * cpml_pair_squared_distance:
 213  * @from: the first #CpmlPair struct
 214  * @to: the second #CpmlPair struct
 215  *
 216  * Gets the squared distance between @from and @to. This value is useful
 217  * for comparation purpose: if you need to get the real distance, use
 218  * cpml_pair_distance().
 219  *
 220  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 221  * will be used.
 222  *
 223  * Returns: the squared distance
 224  **/
 225 double
 226 cpml_pair_squared_distance(const CpmlPair *from, const CpmlPair *to)
 227 {
 228     double x, y;
 229
 230     if (from == NULL)
 231         from = &fallback_pair;
 232     if (to == NULL)
 233         to = &fallback_pair;
 234
 235     x = to->x - from->x;
 236     y = to->y - from->y;
 237
 238     return x * x + y * y;
 239 }
 240
 241 /**
 242  * cpml_pair_distance:
 243  * @from: the first #CpmlPair struct
 244  * @to: the second #CpmlPair struct
 245  * @distance: where to store the result
 246  *
 247  * Gets the distance between @from and @to, storing the result in @distance.
 248  * If you need this value only for comparation purpose, you could use
 249  * cpm_pair_squared_distance() instead.
 250  *
 251  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 252  * will be used.
 253  *
 254  * The algorithm used is adapted from:
 255  * "Replacing Square Roots by Pythagorean Sums"
 256  * by Clave Moler and Donald Morrison (1983)
 257  * IBM Journal of Research and Development 27 (6): 577–581
 258  * http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
 259  *
 260  * Returns: the distance
 261  **/
 262 double
 263 cpml_pair_distance(const CpmlPair *from, const CpmlPair *to)
 264 {
 265     double x, y;
 266     double p, q, r, s;
 267
 268     if (from == NULL)
 269         from = &fallback_pair;
 270     if (to == NULL)
 271         to = &fallback_pair;
 272
 273     x = to->x - from->x;
 274     y = to->y - from->y;
 275
 276     if (x < 0)
 277         x = -x;
 278     if (y < 0)
 279         y = -y;
 280
 281     if (x > y) {
 282         p = x;
 283         q = y;
 284     } else {
 285         p = y;
 286         q = x;
 287     }
 288
 289     if (p > 0) {
 290         for (;;) {
 291             r = q/p;
 292             r *= r;
 293             if (r == 0)
 294                 break;
 295
 296             s = r / (4+r);
 297             p += 2*s*p;
 298             q *= s;
 299         }
 300     }
 301
 302     return p;
 303 }
 304
 305 /**
 306  * cpml_pair_to_cairo:
 307  * @pair: the destination #CpmlPair
 308  * @path_data: the original path data point
 309  *
 310  * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
 311  * operation of cpml_pair_from_cairo().
 312  **/
 313 void
 314 cpml_pair_to_cairo(const CpmlPair *pair, cairo_path_data_t *path_data)
 315 {
 316     path_data->point.x = pair->x;
 317     path_data->point.y = pair->y;
 318 }
 319
 320
 321 /**
 322  * cpml_vector_from_angle:
 323  * @vector: the destination #CpmlVector
 324  * @angle: angle of direction, in radians
 325  *
 326  * Calculates the coordinates of the point far %1 from the origin
 327  * in the @angle direction. The result is stored in @vector.
 328  **/
 329 void
 330 cpml_vector_from_angle(CpmlVector *vector, double angle)
 331 {
 332     /* Check for common conditions */
 333     if (angle == -M_PI_2) {
 334         vector->x = 0;
 335         vector->y = -1;
 336     } else if (angle == M_PI_2) {
 337         vector->x = 0;
 338         vector->y = +1;
 339     } else if (angle == M_PI || angle == -M_PI) {
 340         vector->x = -1;
 341         vector->y = 0;
 342     } else if (angle == 0) {
 343         vector->x = +1;
 344         vector->y = 0;
 345     } else {
 346         vector->x = cos(angle);
 347         vector->y = sin(angle);
 348     }
 349 }
 350
 351 /**
 352  * cpml_vector_set_length:
 353  * @vector: a #CpmlVector
 354  * @length: the new length
 355  *
 356  * Imposes the specified @length to @vector. If the old length is %0
 357  * (and so the direction is not known), nothing happens. If @length
 358  * is %0, @vector is set to (0, 0).
 359  *
 360  * The @length parameter can be negative, in which case the vector
 361  * is inverted.
 362  **/
 363 void
 364 cpml_vector_set_length(CpmlVector *vector, double length)
 365 {
 366     double divisor;
 367
 368     if (length == 0) {
 369         vector->x = 0;
 370         vector->y = 0;
 371         return;
 372     }
 373
 374     divisor = cpml_pair_distance(NULL, vector);
 375
 376     /* Check for valid length (anything other than 0) */
 377     if (divisor != 0) {
 378         divisor /= length;
 379         vector->x /= divisor;
 380         vector->y /= divisor;
 381     }
 382 }
 383
 384 /**
 385  * cpml_vector_angle:
 386  * @vector: the source #CpmlVector
 387  *
 388  * Gets the angle of @vector, in radians. If @vector is (0, 0),
 389  * 0 is returned.
 390  *
 391  * Returns: the angle in radians, a value between -M_PI and M_PI
 392  **/
 393 double
 394 cpml_vector_angle(const CpmlVector *vector)
 395 {
 396     /* Check for common conditions */
 397     if (vector->y == 0)
 398         return vector->x >= 0 ?      0 :  M_PI;
 399     if (vector->x == 0)
 400         return vector->y > 0 ?  M_PI_2 : -M_PI_2;
 401     if (vector->x == vector->y)
 402         return vector->x > 0 ?  M_PI_4 : -M_PI_4 * 3;
 403     if (vector->x == -vector->y)
 404         return vector->x > 0 ? -M_PI_4 :  M_PI_4 * 3;
 405
 406     return atan2(vector->y, vector->x);
 407 }
 408
 409 /**
 410  * cpml_vector_normal:
 411  * @vector: the subject #CpmlVector
 412  *
 413  * Stores in @vector a vector normal to the original @vector.
 414  * The length is retained.
 415  *
 416  * The algorithm is really quick because no trigonometry is involved.
 417  **/
 418 void
 419 cpml_vector_normal(CpmlVector *vector)
 420 {
 421     double tmp = vector->x;
 422
 423     vector->x = -vector->y;
 424     vector->y = tmp;
 425 }
 426
 427 /**
 428  * cpml_vector_transform:
 429  * @vector: the destination #CpmlPair struct
 430  * @matrix: the transformation matrix
 431  *
 432  * Shortcut to apply a specific transformation matrix to @vector.
 433  * It works in a similar way of cpml_pair_transform() but uses
 434  * cairo_matrix_transform_distance() instead of
 435  * cairo_matrix_transform_point().
 436  **/
 437 void
 438 cpml_vector_transform(CpmlPair *vector, const cairo_matrix_t *matrix)
 439 {
 440     cairo_matrix_transform_distance(matrix, &vector->x, &vector->y);
 441 }