src/cpml/cpml-pair.c

   1 /* CPML - Cairo Path Manipulation Library
   2  * Copyright (C) 2007,2008,2009,2010,2011,2012,2013  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  * Since: 1.0
  33  **/
  34
  35 /**
  36  * CpmlPair:
  37  * @x: the x component of the pair
  38  * @y: the y component of the pair
  39  *
  40  * A generic 2D structure.
  41  *
  42  * Since: 1.0
  43  **/
  44
  45 /**
  46  * CpmlVector:
  47  * @x: the x component of the vector
  48  * @y: the y component of the vector
  49  *
  50  * Another name for #CpmlPair. It is used to clarify when a function
  51  * expects a generic pair (usually coordinates) or a vector.
  52  *
  53  * A vector represents a line starting from the origin (0,0) and ending
  54  * to the given coordinates pair. Vectors are useful to define direction
  55  * and length at once. Keep in mind the cairo default coordinates system
  56  * is not problably what you expect: the x axis increases at right
  57  * (as usual) but the y axis increases at down (the reverse of a usual
  58  * cartesian plan). An angle of 0 is at V=(1; 0) (middle right).
  59  *
  60  * Since: 1.0
  61  **/
  62
  63
  64 #include "cpml-internal.h"
  65 #include <string.h>
  66 #include <math.h>
  67
  68
  69 static CpmlPair fallback_pair = { 0, 0 };
  70
  71
  72 /**
  73  * cpml_pair_from_cairo:
  74  * @pair:                     (out): the destination #CpmlPair
  75  * @path_data: (in) (type gpointer): the original path data point
  76  *
  77  * Sets @pair from a #cairo_path_data_t struct. @path_data should contains
  78  * a point data: it is up to the caller to be sure @path_data is valid.
  79  *
  80  * Since: 1.0
  81  **/
  82 void
  83 cpml_pair_from_cairo(CpmlPair *pair, const cairo_path_data_t *path_data)
  84 {
  85     pair->x = path_data->point.x;
  86     pair->y = path_data->point.y;
  87 }
  88
  89 /**
  90  * cpml_pair_copy:
  91  * @pair: (out): the destination #CpmlPair
  92  * @src:  (in):  the source #CpmlPair
  93  *
  94  * Copies @src in @pair. If @src or @pair is %NULL, this function does
  95  * nothing.
  96  *
  97  * Since: 1.0
  98  **/
  99 void
 100 cpml_pair_copy(CpmlPair *pair, const CpmlPair *src)
 101 {
 102     if (pair == NULL || src == NULL)
 103         return;
 104     memcpy(pair, src, sizeof(CpmlPair));
 105 }
 106
 107 /**
 108  * cpml_pair_equal:
 109  * @pair: the first pair to compare
 110  * @src:  the second pair to compare
 111  *
 112  * Compares @pair to @src and returns 1 if the pairs are equals.
 113  * Two %NULL pairs are considered equal.
 114  *
 115  * Returns: (type gboolean): %1 if @pair is equal to @src,
 116  *                           %0 otherwise
 117  *
 118  * Since: 1.0
 119  **/
 120 int
 121 cpml_pair_equal(const CpmlPair *pair, const CpmlPair *src)
 122 {
 123     if (pair == NULL && src == NULL)
 124         return 1;
 125
 126     if (pair == NULL || src == NULL)
 127         return 0;
 128
 129     return pair->x == src->x && pair->y == src->y ? 1 : 0;
 130 }
 131
 132 /**
 133  * cpml_pair_transform:
 134  * @pair:   (inout): the destination #CpmlPair struct
 135  * @matrix: (in):    the transformation matrix
 136  *
 137  * Shortcut to apply a specific transformation matrix to @pair.
 138  *
 139  * Since: 1.0
 140  **/
 141 void
 142 cpml_pair_transform(CpmlPair *pair, const cairo_matrix_t *matrix)
 143 {
 144     cairo_matrix_transform_point(matrix, &pair->x, &pair->y);
 145 }
 146
 147 /**
 148  * cpml_pair_squared_distance:
 149  * @from: the first #CpmlPair struct
 150  * @to:   the second #CpmlPair struct
 151  *
 152  * Gets the squared distance between @from and @to. This value is useful
 153  * for comparation purpose: if you need to get the real distance, use
 154  * cpml_pair_distance().
 155  *
 156  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 157  * will be used.
 158  *
 159  * Returns: the squared distance
 160  *
 161  * Since: 1.0
 162  **/
 163 double
 164 cpml_pair_squared_distance(const CpmlPair *from, const CpmlPair *to)
 165 {
 166     double x, y;
 167
 168     if (from == NULL)
 169         from = &fallback_pair;
 170     if (to == NULL)
 171         to = &fallback_pair;
 172
 173     x = to->x - from->x;
 174     y = to->y - from->y;
 175
 176     return x * x + y * y;
 177 }
 178
 179 /**
 180  * cpml_pair_distance:
 181  * @from: the first #CpmlPair struct
 182  * @to:   the second #CpmlPair struct
 183  *
 184  * Gets the distance between @from and @to. If you need this value only
 185  * for comparation purpose, you could use cpm_pair_squared_distance()
 186  * instead.
 187  *
 188  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 189  * will be used.
 190  *
 191  * The algorithm used is adapted from:
 192  * "Replacing Square Roots by Pythagorean Sums"
 193  * by Clave Moler and Donald Morrison (1983)
 194  * IBM Journal of Research and Development 27 (6): 577–581
 195  * http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
 196  *
 197  * Returns: the distance
 198  *
 199  * Since: 1.0
 200  **/
 201 double
 202 cpml_pair_distance(const CpmlPair *from, const CpmlPair *to)
 203 {
 204     double x, y;
 205     double p, q, r, s;
 206
 207     if (from == NULL)
 208         from = &fallback_pair;
 209     if (to == NULL)
 210         to = &fallback_pair;
 211
 212     x = to->x - from->x;
 213     y = to->y - from->y;
 214
 215     if (x < 0)
 216         x = -x;
 217     if (y < 0)
 218         y = -y;
 219
 220     if (x > y) {
 221         p = x;
 222         q = y;
 223     } else {
 224         p = y;
 225         q = x;
 226     }
 227
 228     if (p > 0) {
 229         for (;;) {
 230             r = q/p;
 231             r *= r;
 232             if (r == 0)
 233                 break;
 234
 235             s = r / (4+r);
 236             p += 2*s*p;
 237             q *= s;
 238         }
 239     }
 240
 241     return p;
 242 }
 243
 244 /**
 245  * cpml_pair_to_cairo:
 246  * @pair:                       (in):  the source #CpmlPair
 247  * @path_data: (out) (type gpointer): the path data point to modify
 248  *
 249  * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
 250  * operation of cpml_pair_from_cairo().
 251  *
 252  * Since: 1.0
 253  **/
 254 void
 255 cpml_pair_to_cairo(const CpmlPair *pair, cairo_path_data_t *path_data)
 256 {
 257     path_data->point.x = pair->x;
 258     path_data->point.y = pair->y;
 259 }
 260
 261
 262 /**
 263  * cpml_vector_from_angle:
 264  * @vector: (out): the destination #CpmlVector
 265  * @angle:  (in):  angle of direction, in radians
 266  *
 267  * Calculates the coordinates of the point far %1 from the origin
 268  * in the @angle direction. The result is stored in @vector.
 269  *
 270  * Since: 1.0
 271  **/
 272 void
 273 cpml_vector_from_angle(CpmlVector *vector, double angle)
 274 {
 275     /* Check for common conditions */
 276     if (angle == -M_PI_2) {
 277         vector->x = 0;
 278         vector->y = -1;
 279     } else if (angle == M_PI_2) {
 280         vector->x = 0;
 281         vector->y = +1;
 282     } else if (angle == M_PI || angle == -M_PI) {
 283         vector->x = -1;
 284         vector->y = 0;
 285     } else if (angle == 0) {
 286         vector->x = +1;
 287         vector->y = 0;
 288     } else {
 289         vector->x = cos(angle);
 290         vector->y = sin(angle);
 291     }
 292 }
 293
 294 /**
 295  * cpml_vector_set_length:
 296  * @vector: (inout): a #CpmlVector
 297  * @length: (in):    the new length
 298  *
 299  * Imposes the specified @length to @vector. If the old length is %0
 300  * (and so the direction is not known), nothing happens. If @length
 301  * is %0, @vector is set to (0, 0).
 302  *
 303  * The @length parameter can be negative, in which case the vector
 304  * is inverted.
 305  *
 306  * Since: 1.0
 307  **/
 308 void
 309 cpml_vector_set_length(CpmlVector *vector, double length)
 310 {
 311     double divisor;
 312
 313     if (length == 0) {
 314         vector->x = 0;
 315         vector->y = 0;
 316         return;
 317     }
 318
 319     divisor = cpml_pair_distance(NULL, vector);
 320
 321     /* Check for valid length (anything other than 0) */
 322     if (divisor != 0) {
 323         divisor /= length;
 324         vector->x /= divisor;
 325         vector->y /= divisor;
 326     }
 327 }
 328
 329 /**
 330  * cpml_vector_angle:
 331  * @vector: the source #CpmlVector
 332  *
 333  * Gets the angle of @vector, in radians. If @vector is (0, 0),
 334  * 0 is returned.
 335  *
 336  * Returns: the angle in radians, a value between -M_PI and M_PI
 337  *
 338  * Since: 1.0
 339  **/
 340 double
 341 cpml_vector_angle(const CpmlVector *vector)
 342 {
 343     /* Check for common conditions */
 344     if (vector->y == 0)
 345         return vector->x >= 0 ?      0 :  M_PI;
 346     if (vector->x == 0)
 347         return vector->y > 0 ?  M_PI_2 : -M_PI_2;
 348     if (vector->x == vector->y)
 349         return vector->x > 0 ?  M_PI_4 : -M_PI_4 * 3;
 350     if (vector->x == -vector->y)
 351         return vector->x > 0 ? -M_PI_4 :  M_PI_4 * 3;
 352
 353     return atan2(vector->y, vector->x);
 354 }
 355
 356 /**
 357  * cpml_vector_normal:
 358  * @vector: (inout): the subject #CpmlVector
 359  *
 360  * Stores in @vector a vector normal to the original @vector.
 361  * The length is retained.
 362  *
 363  * The algorithm is really quick because no trigonometry is involved.
 364  *
 365  * Since: 1.0
 366  **/
 367 void
 368 cpml_vector_normal(CpmlVector *vector)
 369 {
 370     double tmp = vector->x;
 371
 372     vector->x = -vector->y;
 373     vector->y = tmp;
 374 }
 375
 376 /**
 377  * cpml_vector_transform:
 378  * @vector: (inout): the destination #CpmlPair struct
 379  * @matrix: (in):    the transformation matrix
 380  *
 381  * Shortcut to apply a specific transformation matrix to @vector.
 382  * It works in a similar way of cpml_pair_transform() but uses
 383  * cairo_matrix_transform_distance() instead of
 384  * cairo_matrix_transform_point().
 385  *
 386  * Since: 1.0
 387  **/
 388 void
 389 cpml_vector_transform(CpmlPair *vector, const cairo_matrix_t *matrix)
 390 {
 391     cairo_matrix_transform_distance(matrix, &vector->x, &vector->y);
 392 }