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