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: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 /**
 219  * cpml_pair_squared_distance:
 220  * @from: the first #CpmlPair struct
 221  * @to: the second #CpmlPair struct
 222  *
 223  * Gets the squared distance between @from and @to. This value is useful
 224  * for comparation purpose: if you need to get the real distance, use
 225  * cpml_pair_distance().
 226  *
 227  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 228  * will be used.
 229  *
 230  * Return value: the squared distance
 231  **/
 232 double
 233 cpml_pair_squared_distance(const CpmlPair *from, const CpmlPair *to)
 234 {
 235     double x, y;
 236
 237     if (from == NULL)
 238         from = &fallback_pair;
 239     if (to == NULL)
 240         to = &fallback_pair;
 241
 242     x = to->x - from->x;
 243     y = to->y - from->y;
 244
 245     return x * x + y * y;
 246 }
 247
 248 /**
 249  * cpml_pair_distance:
 250  * @from: the first #CpmlPair struct
 251  * @to: the second #CpmlPair struct
 252  * @distance: where to store the result
 253  *
 254  * Gets the distance between @from and @to, storing the result in @distance.
 255  * If you need this value only for comparation purpose, you could use
 256  * cpm_pair_squared_distance() instead.
 257  *
 258  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 259  * will be used.
 260  *
 261  * The algorithm used is adapted from:
 262  * "Replacing Square Roots by Pythagorean Sums"
 263  * by Clave Moler and Donald Morrison (1983)
 264  * IBM Journal of Research and Development 27 (6): 577–581
 265  * http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
 266  *
 267  * Return value: the distance
 268  **/
 269 double
 270 cpml_pair_distance(const CpmlPair *from, const CpmlPair *to)
 271 {
 272     double x, y;
 273     double p, q, r, s;
 274
 275     if (from == NULL)
 276         from = &fallback_pair;
 277     if (to == NULL)
 278         to = &fallback_pair;
 279
 280     x = to->x - from->x;
 281     y = to->y - from->y;
 282
 283     if (x < 0)
 284         x = -x;
 285     if (y < 0)
 286         y = -y;
 287
 288     if (x > y) {
 289         p = x;
 290         q = y;
 291     } else {
 292         p = y;
 293         q = x;
 294     }
 295
 296     if (p > 0) {
 297         for (;;) {
 298             r = q/p;
 299             r *= r;
 300             if (r == 0)
 301                 break;
 302
 303             s = r / (4+r);
 304             p += 2*s*p;
 305             q *= s;
 306         }
 307     }
 308
 309     return p;
 310 }
 311
 312 /**
 313  * cpml_vector_from_angle:
 314  * @vector: the destination #CpmlVector
 315  * @angle: angle of direction, in radians
 316  * @length: the length of the vector
 317  *
 318  * Calculates the coordinates of the point far @length from the origin
 319  * in the @angle direction. The result is stored in @vector.
 320  *
 321  * Return value: @vector
 322  **/
 323 CpmlVector *
 324 cpml_vector_from_angle(CpmlVector *vector, double angle, double length)
 325 {
 326     /* Check for common conditions */
 327     if (angle == -M_PI_2) {
 328         vector->x = 0;
 329         vector->y = -1;
 330         return vector;
 331     }
 332     if (angle == M_PI_2) {
 333         vector->x = 0;
 334         vector->y = +1;
 335         return vector;
 336     }
 337     if (angle == M_PI || angle == -M_PI) {
 338         vector->x = -1;
 339         vector->y = 0;
 340         return vector;
 341     }
 342     if (angle == 0) {
 343         vector->x = +1;
 344         vector->y = 0;
 345         return vector;
 346     }
 347
 348     vector->x = cos(angle);
 349     vector->y = sin(angle);
 350
 351     return vector;
 352 }
 353
 354 /**
 355  * cpml_vector_set_length:
 356  * @vector: a #CpmlVector
 357  * @length: the new length
 358  *
 359  * Imposes the specified @length to @vector. If the old length is 0
 360  * (and so the direction is not known), nothing happens.
 361  **/
 362 void
 363 cpml_vector_set_length(CpmlVector *vector, double length)
 364 {
 365     double divisor = cpml_pair_distance(NULL, vector);
 366
 367     /* Check for valid length (anything other than 0) */
 368     if (divisor <= 0)
 369         return;
 370
 371     divisor /= length;
 372     vector->x /= divisor;
 373     vector->y /= divisor;
 374 }
 375
 376 /**
 377  * cpml_vector_angle:
 378  * @vector: the source #CpmlVector
 379  *
 380  * Gets the angle of @vector, in radians. If @vector is (0, 0),
 381  * 0 is returned.
 382  *
 383  * Return value: the angle in radians, a value between -M_PI and M_PI
 384  **/
 385 double
 386 cpml_vector_angle(const CpmlVector *vector)
 387 {
 388     /* Check for common conditions */
 389     if (vector->y == 0)
 390         return vector->x >= 0 ?      0 :  M_PI;
 391     if (vector->x == 0)
 392         return vector->y > 0 ?  M_PI_2 : -M_PI_2;
 393     if (vector->x == vector->y)
 394         return vector->x > 0 ?  M_PI_4 : -M_PI_4 * 3;
 395     if (vector->x == -vector->y)
 396         return vector->x > 0 ? -M_PI_4 :  M_PI_4 * 3;
 397
 398     return atan2(vector->y, vector->x);
 399 }
 400
 401 /**
 402  * cpml_vector_normal:
 403  * @vector: the subject #CpmlVector
 404  *
 405  * Stores in @vector a vector normal to the original @vector.
 406  * The length is retained.
 407  *
 408  * The algorithm is really quick because no trigonometry is involved.
 409  **/
 410 void
 411 cpml_vector_normal(CpmlVector *vector)
 412 {
 413     double tmp = vector->x;
 414
 415     vector->x = -vector->y;
 416     vector->y = tmp;
 417 }
 418
 419 /**
 420  * cpml_pair_to_cairo:
 421  * @pair: the destination #CpmlPair
 422  * @path_data: the original path data point
 423  *
 424  * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
 425  * operation of cpml_pair_from_cairo().
 426  **/
 427 void
 428 cpml_pair_to_cairo(const CpmlPair *pair, cairo_path_data_t *path_data)
 429 {
 430     path_data->point.x = pair->x;
 431     path_data->point.y = pair->y;
 432 }