src/cpml/cpml-pair.c

   1 /* CPML - Cairo Path Manipulation Library
   2  * Copyright (C) 2008,2009,2010  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
  47  * expects a generic pair (usually coordinates) 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 direction
  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-internal.h"
  59 #include <string.h>
  60 #include <math.h>
  61
  62
  63 static CpmlPair fallback_pair = { 0, 0 };
  64
  65
  66 /**
  67  * cpml_pair_from_cairo:
  68  * @pair: the destination #CpmlPair
  69  * @path_data: the original path data point
  70  *
  71  * Sets @pair from a #cairo_path_data_t struct. @path_data should contains
  72  * a point data: it is up to the caller to be sure @path_data is valid.
  73  **/
  74 void
  75 cpml_pair_from_cairo(CpmlPair *pair, const cairo_path_data_t *path_data)
  76 {
  77     pair->x = path_data->point.x;
  78     pair->y = path_data->point.y;
  79 }
  80
  81 /**
  82  * cpml_pair_copy:
  83  * @pair: the destination #CpmlPair
  84  * @src: the source #CpmlPair
  85  *
  86  * Copies @src in @pair.
  87  **/
  88 void
  89 cpml_pair_copy(CpmlPair *pair, const CpmlPair *src)
  90 {
  91     memcpy(pair, src, sizeof(CpmlPair));
  92 }
  93
  94 /**
  95  * cpml_pair_transform:
  96  * @pair: the destination #CpmlPair struct
  97  * @matrix: the transformation matrix
  98  *
  99  * Shortcut to apply a specific transformation matrix to @pair.
 100  **/
 101 void
 102 cpml_pair_transform(CpmlPair *pair, const cairo_matrix_t *matrix)
 103 {
 104     cairo_matrix_transform_point(matrix, &pair->x, &pair->y);
 105 }
 106
 107 /**
 108  * cpml_pair_squared_distance:
 109  * @from: the first #CpmlPair struct
 110  * @to: the second #CpmlPair struct
 111  *
 112  * Gets the squared distance between @from and @to. This value is useful
 113  * for comparation purpose: if you need to get the real distance, use
 114  * cpml_pair_distance().
 115  *
 116  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 117  * will be used.
 118  *
 119  * Returns: the squared distance
 120  **/
 121 double
 122 cpml_pair_squared_distance(const CpmlPair *from, const CpmlPair *to)
 123 {
 124     double x, y;
 125
 126     if (from == NULL)
 127         from = &fallback_pair;
 128     if (to == NULL)
 129         to = &fallback_pair;
 130
 131     x = to->x - from->x;
 132     y = to->y - from->y;
 133
 134     return x * x + y * y;
 135 }
 136
 137 /**
 138  * cpml_pair_distance:
 139  * @from: the first #CpmlPair struct
 140  * @to: the second #CpmlPair struct
 141  * @distance: where to store the result
 142  *
 143  * Gets the distance between @from and @to, storing the result in @distance.
 144  * If you need this value only for comparation purpose, you could use
 145  * cpm_pair_squared_distance() instead.
 146  *
 147  * @from or @to could be %NULL, in which case the fallback (0, 0) pair
 148  * will be used.
 149  *
 150  * The algorithm used is adapted from:
 151  * "Replacing Square Roots by Pythagorean Sums"
 152  * by Clave Moler and Donald Morrison (1983)
 153  * IBM Journal of Research and Development 27 (6): 577–581
 154  * http://www.research.ibm.com/journal/rd/276/ibmrd2706P.pdf
 155  *
 156  * Returns: the distance
 157  **/
 158 double
 159 cpml_pair_distance(const CpmlPair *from, const CpmlPair *to)
 160 {
 161     double x, y;
 162     double p, q, r, s;
 163
 164     if (from == NULL)
 165         from = &fallback_pair;
 166     if (to == NULL)
 167         to = &fallback_pair;
 168
 169     x = to->x - from->x;
 170     y = to->y - from->y;
 171
 172     if (x < 0)
 173         x = -x;
 174     if (y < 0)
 175         y = -y;
 176
 177     if (x > y) {
 178         p = x;
 179         q = y;
 180     } else {
 181         p = y;
 182         q = x;
 183     }
 184
 185     if (p > 0) {
 186         for (;;) {
 187             r = q/p;
 188             r *= r;
 189             if (r == 0)
 190                 break;
 191
 192             s = r / (4+r);
 193             p += 2*s*p;
 194             q *= s;
 195         }
 196     }
 197
 198     return p;
 199 }
 200
 201 /**
 202  * cpml_pair_to_cairo:
 203  * @pair: the destination #CpmlPair
 204  * @path_data: the original path data point
 205  *
 206  * Sets a #cairo_path_data_t struct to @pair. This is exactly the reverse
 207  * operation of cpml_pair_from_cairo().
 208  **/
 209 void
 210 cpml_pair_to_cairo(const CpmlPair *pair, cairo_path_data_t *path_data)
 211 {
 212     path_data->point.x = pair->x;
 213     path_data->point.y = pair->y;
 214 }
 215
 216
 217 /**
 218  * cpml_vector_from_angle:
 219  * @vector: the destination #CpmlVector
 220  * @angle: angle of direction, in radians
 221  *
 222  * Calculates the coordinates of the point far %1 from the origin
 223  * in the @angle direction. The result is stored in @vector.
 224  **/
 225 void
 226 cpml_vector_from_angle(CpmlVector *vector, double angle)
 227 {
 228     /* Check for common conditions */
 229     if (angle == -M_PI_2) {
 230         vector->x = 0;
 231         vector->y = -1;
 232     } else if (angle == M_PI_2) {
 233         vector->x = 0;
 234         vector->y = +1;
 235     } else if (angle == M_PI || angle == -M_PI) {
 236         vector->x = -1;
 237         vector->y = 0;
 238     } else if (angle == 0) {
 239         vector->x = +1;
 240         vector->y = 0;
 241     } else {
 242         vector->x = cos(angle);
 243         vector->y = sin(angle);
 244     }
 245 }
 246
 247 /**
 248  * cpml_vector_set_length:
 249  * @vector: a #CpmlVector
 250  * @length: the new length
 251  *
 252  * Imposes the specified @length to @vector. If the old length is %0
 253  * (and so the direction is not known), nothing happens. If @length
 254  * is %0, @vector is set to (0, 0).
 255  *
 256  * The @length parameter can be negative, in which case the vector
 257  * is inverted.
 258  **/
 259 void
 260 cpml_vector_set_length(CpmlVector *vector, double length)
 261 {
 262     double divisor;
 263
 264     if (length == 0) {
 265         vector->x = 0;
 266         vector->y = 0;
 267         return;
 268     }
 269
 270     divisor = cpml_pair_distance(NULL, vector);
 271
 272     /* Check for valid length (anything other than 0) */
 273     if (divisor != 0) {
 274         divisor /= length;
 275         vector->x /= divisor;
 276         vector->y /= divisor;
 277     }
 278 }
 279
 280 /**
 281  * cpml_vector_angle:
 282  * @vector: the source #CpmlVector
 283  *
 284  * Gets the angle of @vector, in radians. If @vector is (0, 0),
 285  * 0 is returned.
 286  *
 287  * Returns: the angle in radians, a value between -M_PI and M_PI
 288  **/
 289 double
 290 cpml_vector_angle(const CpmlVector *vector)
 291 {
 292     /* Check for common conditions */
 293     if (vector->y == 0)
 294         return vector->x >= 0 ?      0 :  M_PI;
 295     if (vector->x == 0)
 296         return vector->y > 0 ?  M_PI_2 : -M_PI_2;
 297     if (vector->x == vector->y)
 298         return vector->x > 0 ?  M_PI_4 : -M_PI_4 * 3;
 299     if (vector->x == -vector->y)
 300         return vector->x > 0 ? -M_PI_4 :  M_PI_4 * 3;
 301
 302     return atan2(vector->y, vector->x);
 303 }
 304
 305 /**
 306  * cpml_vector_normal:
 307  * @vector: the subject #CpmlVector
 308  *
 309  * Stores in @vector a vector normal to the original @vector.
 310  * The length is retained.
 311  *
 312  * The algorithm is really quick because no trigonometry is involved.
 313  **/
 314 void
 315 cpml_vector_normal(CpmlVector *vector)
 316 {
 317     double tmp = vector->x;
 318
 319     vector->x = -vector->y;
 320     vector->y = tmp;
 321 }
 322
 323 /**
 324  * cpml_vector_transform:
 325  * @vector: the destination #CpmlPair struct
 326  * @matrix: the transformation matrix
 327  *
 328  * Shortcut to apply a specific transformation matrix to @vector.
 329  * It works in a similar way of cpml_pair_transform() but uses
 330  * cairo_matrix_transform_distance() instead of
 331  * cairo_matrix_transform_point().
 332  **/
 333 void
 334 cpml_vector_transform(CpmlPair *vector, const cairo_matrix_t *matrix)
 335 {
 336     cairo_matrix_transform_distance(matrix, &vector->x, &vector->y);
 337 }