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 void
  76 cpml_pair_copy(CpmlPair *pair, const CpmlPair *src)
  77 {
  78     memcpy(pair, src, sizeof(CpmlPair));
  79 }
  80
  81 /**
  82  * cpml_pair_from_cairo:
  83  * @pair: the destination #CpmlPair
  84  * @path_data: the original path data point
  85  *
  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.
  88  **/
  89 void
  90 cpml_pair_from_cairo(CpmlPair *pair, const cairo_path_data_t *path_data)
  91 {
  92     pair->x = path_data->point.x;
  93     pair->y = path_data->point.y;
  94 }
  95
  96
  97 /**
  98  * cpml_pair_negate:
  99  * @pair: a #CpmlPair
 100  *
 101  * Negates the coordinates of @pair.
 102  **/
 103 void
 104 cpml_pair_negate(CpmlPair *pair)
 105 {
 106     pair->x = - pair->x;
 107     pair->y = - pair->y;
 108 }
 109
 110 /**
 111  * cpml_pair_invert:
 112  * @pair: a #CpmlPair
 113  *
 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
 116  * performed.
 117  *
 118  * Return value: 1 on success, 0 on errors
 119  **/
 120 cairo_bool_t
 121 cpml_pair_invert(CpmlPair *pair)
 122 {
 123     if (pair->x == 0 || pair->y == 0)
 124         return 0;
 125
 126     pair->x = 1. / pair->x;
 127     pair->y = 1. / pair->y;
 128     return 1;
 129 }
 130
 131 /**
 132  * cpml_pair_add:
 133  * @pair: the destination #CpmlPair
 134  * @src:  the source pair to add
 135  *
 136  * Adds @src to @pair and stores the result in @pair. In other words,
 137  * @pair = @pair + @src.
 138  **/
 139 void
 140 cpml_pair_add(CpmlPair *pair, const CpmlPair *src)
 141 {
 142     pair->x += src->x;
 143     pair->y += src->y;
 144 }
 145
 146 /**
 147  * cpml_pair_sub:
 148  * @pair: the destination #CpmlPair
 149  * @src:  the source pair to subtract
 150  *
 151  * Subtracts @src from @pair and stores the result in @pair. In other words,
 152  * @pair = @pair - @src.
 153  **/
 154 void
 155 cpml_pair_sub(CpmlPair *pair, const CpmlPair *src)
 156 {
 157     pair->x -= src->x;
 158     pair->y -= src->y;
 159 }
 160
 161 /**
 162  * cpml_pair_mul:
 163  * @pair: the destination #CpmlPair
 164  * @src:  the source pair factor
 165  *
 166  * Multiplies the x coordinate of @pair by the @src x factor and the
 167  * y coordinate by the @src y factor.
 168  **/
 169 void
 170 cpml_pair_mul(CpmlPair *pair, const CpmlPair *src)
 171 {
 172     pair->x *= src->x;
 173     pair->y *= src->y;
 174 }
 175
 176 /**
 177  * cpml_pair_div:
 178  * @pair: the destination #CpmlPair
 179  * @src:  the source pair divisor
 180  *
 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
 184  * is performed.
 185  *
 186  * Return value: 1 on success, 0 on errors
 187  **/
 188 cairo_bool_t
 189 cpml_pair_div(CpmlPair *pair, const CpmlPair *src)
 190 {
 191     if (src->x == 0 || src->y == 0)
 192         return 0;
 193
 194     pair->x /= src->x;
 195     pair->y /= src->y;
 196     return 1;
 197 }
 198
 199 /**
 200  * cpml_pair_transform:
 201  * @pair: the destination #CpmlPair struct
 202  * @matrix: the transformation matrix
 203  *
 204  * Shortcut to apply a specific transformation matrix to @pair.
 205  **/
 206 void
 207 cpml_pair_transform(CpmlPair *pair, const cairo_matrix_t *matrix)
 208 {
 209     cairo_matrix_transform_point(matrix, &pair->x, &pair->y);
 210 }
 211
 212 /**
 213  * cpml_pair_squared_distance:
 214  * @from: the first #CpmlPair struct
 215  * @to: the second #CpmlPair struct
 216  *
 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().
 220  *
 221  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 222  * will be used.
 223  *
 224  * Return value: the squared distance
 225  **/
 226 double
 227 cpml_pair_squared_distance(const CpmlPair *from, const CpmlPair *to)
 228 {
 229     double x, y;
 230
 231     if (from == NULL)
 232         from = &fallback_pair;
 233     if (to == NULL)
 234         to = &fallback_pair;
 235
 236     x = to->x - from->x;
 237     y = to->y - from->y;
 238
 239     return x * x + y * y;
 240 }
 241
 242 /**
 243  * cpml_pair_distance:
 244  * @from: the first #CpmlPair struct
 245  * @to: the second #CpmlPair struct
 246  * @distance: where to store the result
 247  *
 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.
 251  *
 252  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 253  * will be used.
 254  *
 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
 260  *
 261  * Return value: the distance
 262  **/
 263 double
 264 cpml_pair_distance(const CpmlPair *from, const CpmlPair *to)
 265 {
 266     double x, y;
 267     double p, q, r, s;
 268
 269     if (from == NULL)
 270         from = &fallback_pair;
 271     if (to == NULL)
 272         to = &fallback_pair;
 273
 274     x = to->x - from->x;
 275     y = to->y - from->y;
 276
 277     if (x < 0)
 278         x = -x;
 279     if (y < 0)
 280         y = -y;
 281
 282     if (x > y) {
 283         p = x;
 284         q = y;
 285     } else {
 286         p = y;
 287         q = x;
 288     }
 289
 290     if (p > 0) {
 291         for (;;) {
 292             r = q/p;
 293             r *= r;
 294             if (r == 0)
 295                 break;
 296
 297             s = r / (4+r);
 298             p += 2*s*p;
 299             q *= s;
 300         }
 301     }
 302
 303     return p;
 304 }
 305
 306 /**
 307  * cpml_pair_to_cairo:
 308  * @pair: the destination #CpmlPair
 309  * @path_data: the original path data point
 310  *
 311  * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
 312  * operation of cpml_pair_from_cairo().
 313  **/
 314 void
 315 cpml_pair_to_cairo(const CpmlPair *pair, cairo_path_data_t *path_data)
 316 {
 317     path_data->point.x = pair->x;
 318     path_data->point.y = pair->y;
 319 }
 320
 321
 322 /**
 323  * cpml_vector_from_angle:
 324  * @vector: the destination #CpmlVector
 325  * @angle: angle of direction, in radians
 326  *
 327  * Calculates the coordinates of the point far %1 from the origin
 328  * in the @angle direction. The result is stored in @vector.
 329  **/
 330 void
 331 cpml_vector_from_angle(CpmlVector *vector, double angle)
 332 {
 333     /* Check for common conditions */
 334     if (angle == -M_PI_2) {
 335         vector->x = 0;
 336         vector->y = -1;
 337     } else if (angle == M_PI_2) {
 338         vector->x = 0;
 339         vector->y = +1;
 340     } else if (angle == M_PI || angle == -M_PI) {
 341         vector->x = -1;
 342         vector->y = 0;
 343     } else if (angle == 0) {
 344         vector->x = +1;
 345         vector->y = 0;
 346     } else {
 347         vector->x = cos(angle);
 348         vector->y = sin(angle);
 349     }
 350 }
 351
 352 /**
 353  * cpml_vector_set_length:
 354  * @vector: a #CpmlVector
 355  * @length: the new length
 356  *
 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).
 360  *
 361  * The @length parameter can be negative, in which case the vector
 362  * is inverted.
 363  **/
 364 void
 365 cpml_vector_set_length(CpmlVector *vector, double length)
 366 {
 367     double divisor;
 368
 369     if (length == 0) {
 370         vector->x = 0;
 371         vector->y = 0;
 372         return;
 373     }
 374
 375     divisor = cpml_pair_distance(NULL, vector);
 376
 377     /* Check for valid length (anything other than 0) */
 378     if (divisor != 0) {
 379         divisor /= length;
 380         vector->x /= divisor;
 381         vector->y /= divisor;
 382     }
 383 }
 384
 385 /**
 386  * cpml_vector_angle:
 387  * @vector: the source #CpmlVector
 388  *
 389  * Gets the angle of @vector, in radians. If @vector is (0, 0),
 390  * 0 is returned.
 391  *
 392  * Return value: the angle in radians, a value between -M_PI and M_PI
 393  **/
 394 double
 395 cpml_vector_angle(const CpmlVector *vector)
 396 {
 397     /* Check for common conditions */
 398     if (vector->y == 0)
 399         return vector->x >= 0 ?      0 :  M_PI;
 400     if (vector->x == 0)
 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;
 406
 407     return atan2(vector->y, vector->x);
 408 }
 409
 410 /**
 411  * cpml_vector_normal:
 412  * @vector: the subject #CpmlVector
 413  *
 414  * Stores in @vector a vector normal to the original @vector.
 415  * The length is retained.
 416  *
 417  * The algorithm is really quick because no trigonometry is involved.
 418  **/
 419 void
 420 cpml_vector_normal(CpmlVector *vector)
 421 {
 422     double tmp = vector->x;
 423
 424     vector->x = -vector->y;
 425     vector->y = tmp;
 426 }
 427
 428 /**
 429  * cpml_vector_transform:
 430  * @vector: the destination #CpmlPair struct
 431  * @matrix: the transformation matrix
 432  *
 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().
 437  **/
 438 void
 439 cpml_vector_transform(CpmlPair *vector, const cairo_matrix_t *matrix)
 440 {
 441     cairo_matrix_transform_distance(matrix, &vector->x, &vector->y);
 442 }