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