src/cpml/cpml-pair.c

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