gfx/src/nsCoord.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef NSCOORD_H
  39 #define NSCOORD_H
  40
  41 #include "nscore.h"
  42 #include "nsMathUtils.h"
  43 #include <math.h>
  44 #include <float.h>
  45
  46 #include "nsDebug.h"
  47
  48 /*
  49  * Basic type used for the geometry classes.
  50  *
  51  * Normally all coordinates are maintained in an app unit coordinate
  52  * space. An app unit is 1/60th of a CSS device pixel, which is, in turn
  53  * an integer number of device pixels, such at the CSS DPI is as close to
  54  * 96dpi as possible.
  55  */
  56
  57 // This controls whether we're using integers or floats for coordinates. We
  58 // want to eventually use floats. If you change this, you need to manually
  59 // change the definition of nscoord in gfx/src/gfxidltypes.idl.
  60 //#define NS_COORD_IS_FLOAT
  61
  62 inline float NS_IEEEPositiveInfinity() {
  63   union { PRUint32 mPRUint32; float mFloat; } pun;
  64   pun.mPRUint32 = 0x7F800000;
  65   return pun.mFloat;
  66 }
  67 inline PRBool NS_IEEEIsNan(float aF) {
  68   union { PRUint32 mBits; float mFloat; } pun;
  69   pun.mFloat = aF;
  70   return (pun.mBits & 0x7F800000) == 0x7F800000 &&
  71     (pun.mBits & 0x007FFFFF) != 0;
  72 }
  73
  74 #ifdef NS_COORD_IS_FLOAT
  75 typedef float nscoord;
  76 #define nscoord_MAX NS_IEEEPositiveInfinity()
  77 #else
  78 typedef PRInt32 nscoord;
  79 #define nscoord_MAX nscoord(1 << 30)
  80 #endif
  81
  82 #define nscoord_MIN (-nscoord_MAX)
  83
  84 inline void VERIFY_COORD(nscoord aCoord) {
  85 #ifdef NS_COORD_IS_FLOAT
  86   NS_ASSERTION(floorf(aCoord) == aCoord,
  87                "Coords cannot have fractions");
  88 #endif
  89 }
  90
  91 inline nscoord NSToCoordRound(float aValue)
  92 {
  93 #if defined(XP_WIN32) && defined(_M_IX86) && !defined(__GNUC__)
  94   return NS_lroundup30(aValue);
  95 #else
  96   return nscoord(NS_floorf(aValue + 0.5f));
  97 #endif /* XP_WIN32 && _M_IX86 && !__GNUC__ */
  98 }
  99
 100 inline nscoord NSToCoordRoundWithClamp(float aValue)
 101 {
 102 #ifndef NS_COORD_IS_FLOAT
 103   // Bounds-check before converting out of float, to avoid overflow
 104   if (aValue >= nscoord_MAX) {
 105     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 106     return nscoord_MAX;
 107   }
 108   if (aValue <= nscoord_MIN) {
 109     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 110     return nscoord_MIN;
 111   }
 112 #endif
 113   return NSToCoordRound(aValue);
 114 }
 115
 116 /**
 117  * Returns aCoord * aScale, capping the product to nscoord_MAX or nscoord_MIN as
 118  * appropriate for the signs of aCoord and aScale.  If requireNotNegative is
 119  * true, this method will enforce that aScale is not negative; use that
 120  * parametrization to get a check of that fact in debug builds.
 121  */
 122 inline nscoord _nscoordSaturatingMultiply(nscoord aCoord, float aScale,
 123                                           PRBool requireNotNegative) {
 124   VERIFY_COORD(aCoord);
 125   if (requireNotNegative) {
 126     NS_ABORT_IF_FALSE(aScale >= 0.0f,
 127                       "negative scaling factors must be handled manually");
 128   }
 129 #ifdef NS_COORD_IS_FLOAT
 130   return floorf(aCoord * aScale);
 131 #else
 132   // This one's only a warning because it may be possible to trigger it with
 133   // valid inputs.
 134   NS_WARN_IF_FALSE((requireNotNegative
 135                     ? aCoord > 0
 136                     : (aCoord > 0) == (aScale > 0))
 137                    ? floorf(aCoord * aScale) < nscoord_MAX
 138                    : ceilf(aCoord * aScale) > nscoord_MIN,
 139                    "nscoord multiplication capped");
 140
 141   float product = aCoord * aScale;
 142   if (requireNotNegative ? aCoord > 0 : (aCoord > 0) == (aScale > 0))
 143     return NSToCoordRoundWithClamp(PR_MIN(nscoord_MAX, product));
 144   return NSToCoordRoundWithClamp(PR_MAX(nscoord_MIN, product));
 145 #endif
 146 }
 147
 148 /**
 149  * Returns aCoord * aScale, capping the product to nscoord_MAX or nscoord_MIN as
 150  * appropriate for the sign of aCoord.  This method requires aScale to not be
 151  * negative; use this method when you know that aScale should never be
 152  * negative to get a sanity check of that invariant in debug builds.
 153  */
 154 inline nscoord NSCoordSaturatingNonnegativeMultiply(nscoord aCoord, float aScale) {
 155   return _nscoordSaturatingMultiply(aCoord, aScale, PR_TRUE);
 156 }
 157
 158 /**
 159  * Returns aCoord * aScale, capping the product to nscoord_MAX or nscoord_MIN as
 160  * appropriate for the signs of aCoord and aScale.
 161  */
 162 inline nscoord NSCoordSaturatingMultiply(nscoord aCoord, float aScale) {
 163   return _nscoordSaturatingMultiply(aCoord, aScale, PR_FALSE);
 164 }
 165
 166 inline nscoord NSCoordMultiply(nscoord aCoord, PRInt32 aScale) {
 167   VERIFY_COORD(aCoord);
 168   return aCoord * aScale;
 169 }
 170
 171 inline nscoord NSCoordDivide(nscoord aCoord, float aVal) {
 172   VERIFY_COORD(aCoord);
 173 #ifdef NS_COORD_IS_FLOAT
 174   return floorf(aCoord/aVal);
 175 #else
 176   return (PRInt32)(aCoord/aVal);
 177 #endif
 178 }
 179
 180 inline nscoord NSCoordDivide(nscoord aCoord, PRInt32 aVal) {
 181   VERIFY_COORD(aCoord);
 182 #ifdef NS_COORD_IS_FLOAT
 183   return floorf(aCoord/aVal);
 184 #else
 185   return aCoord/aVal;
 186 #endif
 187 }
 188
 189 /**
 190  * Returns a + b, capping the sum to nscoord_MAX.
 191  *
 192  * This function assumes that neither argument is nscoord_MIN.
 193  *
 194  * Note: If/when we start using floats for nscoords, this function won't be as
 195  * necessary.  Normal float addition correctly handles adding with infinity,
 196  * assuming we aren't adding nscoord_MIN. (-infinity)
 197  */
 198 inline nscoord
 199 NSCoordSaturatingAdd(nscoord a, nscoord b)
 200 {
 201   VERIFY_COORD(a);
 202   VERIFY_COORD(b);
 203   NS_ASSERTION(a != nscoord_MIN && b != nscoord_MIN,
 204                "NSCoordSaturatingAdd got nscoord_MIN as argument");
 205
 206 #ifdef NS_COORD_IS_FLOAT
 207   // Float math correctly handles a+b, given that neither is -infinity.
 208   return a + b;
 209 #else
 210   if (a == nscoord_MAX || b == nscoord_MAX) {
 211     // infinity + anything = anything + infinity = infinity
 212     return nscoord_MAX;
 213   } else {
 214     // a + b = a + b
 215     NS_ASSERTION(a < nscoord_MAX && b < nscoord_MAX,
 216                  "Doing nscoord addition with values > nscoord_MAX");
 217     NS_ASSERTION((PRInt64)a + (PRInt64)b > (PRInt64)nscoord_MIN,
 218                  "nscoord addition will reach or pass nscoord_MIN");
 219     // This one's only a warning because the PR_MIN below means that
 220     // we'll handle this case correctly.
 221     NS_WARN_IF_FALSE((PRInt64)a + (PRInt64)b < (PRInt64)nscoord_MAX,
 222                      "nscoord addition capped to nscoord_MAX");
 223
 224     // Cap the result, just in case we're dealing with numbers near nscoord_MAX
 225     return PR_MIN(nscoord_MAX, a + b);
 226   }
 227 #endif
 228 }
 229
 230 /**
 231  * Returns a - b, gracefully handling cases involving nscoord_MAX.
 232  * This function assumes that neither argument is nscoord_MIN.
 233  *
 234  * The behavior is as follows:
 235  *
 236  *  a)  infinity - infinity -> infMinusInfResult
 237  *  b)  N - infinity        -> 0  (unexpected -- triggers NOTREACHED)
 238  *  c)  infinity - N        -> infinity
 239  *  d)  N1 - N2             -> N1 - N2
 240  *
 241  * Note: For float nscoords, cases (c) and (d) are handled by normal float
 242  * math.  We still need to explicitly specify the behavior for cases (a)
 243  * and (b), though.  (Under normal float math, those cases would return NaN
 244  * and -infinity, respectively.)
 245  */
 246 inline nscoord
 247 NSCoordSaturatingSubtract(nscoord a, nscoord b,
 248                           nscoord infMinusInfResult)
 249 {
 250   VERIFY_COORD(a);
 251   VERIFY_COORD(b);
 252   NS_ASSERTION(a != nscoord_MIN && b != nscoord_MIN,
 253                "NSCoordSaturatingSubtract got nscoord_MIN as argument");
 254
 255   if (b == nscoord_MAX) {
 256     if (a == nscoord_MAX) {
 257       // case (a)
 258       return infMinusInfResult;
 259     } else {
 260       // case (b)
 261       NS_NOTREACHED("Attempted to subtract [n - nscoord_MAX]");
 262       return 0;
 263     }
 264   } else {
 265 #ifdef NS_COORD_IS_FLOAT
 266     // case (c) and (d) for floats.  (float math handles both)
 267     return a - b;
 268 #else
 269     if (a == nscoord_MAX) {
 270       // case (c) for integers
 271       return nscoord_MAX;
 272     } else {
 273       // case (d) for integers
 274       NS_ASSERTION(a < nscoord_MAX && b < nscoord_MAX,
 275                    "Doing nscoord subtraction with values > nscoord_MAX");
 276       NS_ASSERTION((PRInt64)a - (PRInt64)b > (PRInt64)nscoord_MIN,
 277                    "nscoord subtraction will reach or pass nscoord_MIN");
 278       // This one's only a warning because the PR_MIN below means that
 279       // we'll handle this case correctly.
 280       NS_WARN_IF_FALSE((PRInt64)a - (PRInt64)b < (PRInt64)nscoord_MAX,
 281                        "nscoord subtraction capped to nscoord_MAX");
 282
 283       // Cap the result, in case we're dealing with numbers near nscoord_MAX
 284       return PR_MIN(nscoord_MAX, a - b);
 285     }
 286   }
 287 #endif
 288 }
 289 /** compare against a nscoord "b", which might be unconstrained
 290   * "a" must not be unconstrained.
 291   * Every number is smaller than a unconstrained one
 292   */
 293 inline PRBool
 294 NSCoordLessThan(nscoord a,nscoord b)
 295 {
 296   NS_ASSERTION(a != nscoord_MAX,
 297                "This coordinate should be constrained");
 298   return ((a < b) || (b == nscoord_MAX));
 299 }
 300
 301 /** compare against a nscoord "b", which might be unconstrained
 302   * "a" must not be unconstrained
 303   * No number is larger than a unconstrained one.
 304   */
 305 inline PRBool
 306 NSCoordGreaterThan(nscoord a,nscoord b)
 307 {
 308   NS_ASSERTION(a != nscoord_MAX,
 309                "This coordinate should be constrained");
 310   return ((a > b) && (b != nscoord_MAX));
 311 }
 312
 313 /**
 314  * Convert an nscoord to a PRInt32. This *does not* do rounding because
 315  * coords are never fractional. They can be out of range, so this does
 316  * clamp out of bounds coord values to PR_INT32_MIN and PR_INT32_MAX.
 317  */
 318 inline PRInt32 NSCoordToInt(nscoord aCoord) {
 319   VERIFY_COORD(aCoord);
 320 #ifdef NS_COORD_IS_FLOAT
 321   NS_ASSERTION(!NS_IEEEIsNan(aCoord), "NaN encountered in int conversion");
 322   if (aCoord < -2147483648.0f) {
 323     // -2147483648 is the smallest 32-bit signed integer that can be
 324     // exactly represented as a float
 325     return PR_INT32_MIN;
 326   } else if (aCoord > 2147483520.0f) {
 327     // 2147483520 is the largest 32-bit signed integer that can be
 328     // exactly represented as an IEEE float
 329     return PR_INT32_MAX;
 330   } else {
 331     return (PRInt32)aCoord;
 332   }
 333 #else
 334   return aCoord;
 335 #endif
 336 }
 337
 338 inline float NSCoordToFloat(nscoord aCoord) {
 339   VERIFY_COORD(aCoord);
 340 #ifdef NS_COORD_IS_FLOAT
 341   NS_ASSERTION(!NS_IEEEIsNan(aCoord), "NaN encountered in float conversion");
 342 #endif
 343   return (float)aCoord;
 344 }
 345
 346 /*
 347  * Coord Rounding Functions
 348  */
 349 inline nscoord NSToCoordFloor(float aValue)
 350 {
 351   return nscoord(NS_floorf(aValue));
 352 }
 353
 354 inline nscoord NSToCoordFloorClamped(float aValue)
 355 {
 356 #ifndef NS_COORD_IS_FLOAT
 357   // Bounds-check before converting out of float, to avoid overflow
 358   if (aValue >= nscoord_MAX) {
 359     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 360     return nscoord_MAX;
 361   }
 362   if (aValue <= nscoord_MIN) {
 363     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 364     return nscoord_MIN;
 365   }
 366 #endif
 367   return NSToCoordFloor(aValue);
 368 }
 369
 370 inline nscoord NSToCoordCeil(float aValue)
 371 {
 372   return nscoord(NS_ceilf(aValue));
 373 }
 374
 375 inline nscoord NSToCoordCeilClamped(float aValue)
 376 {
 377 #ifndef NS_COORD_IS_FLOAT
 378   // Bounds-check before converting out of float, to avoid overflow
 379   if (aValue >= nscoord_MAX) {
 380     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 381     return nscoord_MAX;
 382   }
 383   if (aValue <= nscoord_MIN) {
 384     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 385     return nscoord_MIN;
 386   }
 387 #endif
 388   return NSToCoordCeil(aValue);
 389 }
 390
 391 /*
 392  * Int Rounding Functions
 393  */
 394 inline PRInt32 NSToIntFloor(float aValue)
 395 {
 396   return PRInt32(NS_floorf(aValue));
 397 }
 398
 399 inline PRInt32 NSToIntCeil(float aValue)
 400 {
 401   return PRInt32(NS_ceilf(aValue));
 402 }
 403
 404 inline PRInt32 NSToIntRound(float aValue)
 405 {
 406   return NS_lroundf(aValue);
 407 }
 408
 409 inline PRInt32 NSToIntRoundUp(float aValue)
 410 {
 411   return PRInt32(NS_floorf(aValue + 0.5f));
 412 }
 413
 414 /*
 415  * App Unit/Pixel conversions
 416  */
 417 inline nscoord NSFloatPixelsToAppUnits(float aPixels, float aAppUnitsPerPixel)
 418 {
 419   return NSToCoordRoundWithClamp(aPixels * aAppUnitsPerPixel);
 420 }
 421
 422 inline nscoord NSIntPixelsToAppUnits(PRInt32 aPixels, PRInt32 aAppUnitsPerPixel)
 423 {
 424   // The cast to nscoord makes sure we don't overflow if we ever change
 425   // nscoord to float
 426   nscoord r = aPixels * (nscoord)aAppUnitsPerPixel;
 427   VERIFY_COORD(r);
 428   return r;
 429 }
 430
 431 inline float NSAppUnitsToFloatPixels(nscoord aAppUnits, float aAppUnitsPerPixel)
 432 {
 433   return (float(aAppUnits) / aAppUnitsPerPixel);
 434 }
 435
 436 inline PRInt32 NSAppUnitsToIntPixels(nscoord aAppUnits, float aAppUnitsPerPixel)
 437 {
 438   return NSToIntRound(float(aAppUnits) / aAppUnitsPerPixel);
 439 }
 440
 441 inline float NSCoordScale(nscoord aCoord, PRInt32 aFromAPP, PRInt32 aToAPP)
 442 {
 443   return (NSCoordToFloat(aCoord) * aToAPP) / aFromAPP;
 444 }
 445
 446 /// handy constants
 447 #define TWIPS_PER_POINT_INT           20
 448 #define TWIPS_PER_POINT_FLOAT         20.0f
 449 #define POINTS_PER_INCH_INT           72
 450 #define POINTS_PER_INCH_FLOAT         72.0f
 451 #define CM_PER_INCH_FLOAT             2.54f
 452 #define MM_PER_INCH_FLOAT             25.4f
 453
 454 /*
 455  * Twips/unit conversions
 456  */
 457 inline float NSUnitsToTwips(float aValue, float aPointsPerUnit)
 458 {
 459   return aValue * aPointsPerUnit * TWIPS_PER_POINT_FLOAT;
 460 }
 461
 462 inline float NSTwipsToUnits(float aTwips, float aUnitsPerPoint)
 463 {
 464   return (aTwips * (aUnitsPerPoint / TWIPS_PER_POINT_FLOAT));
 465 }
 466
 467 /// Unit conversion macros
 468 //@{
 469 #define NS_POINTS_TO_TWIPS(x)         NSUnitsToTwips((x), 1.0f)
 470 #define NS_INCHES_TO_TWIPS(x)         NSUnitsToTwips((x), POINTS_PER_INCH_FLOAT)                      // 72 points per inch
 471
 472 #define NS_MILLIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.03937f))
 473 #define NS_CENTIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.3937f))
 474
 475 #define NS_PICAS_TO_TWIPS(x)          NSUnitsToTwips((x), 12.0f)                      // 12 points per pica
 476
 477 #define NS_POINTS_TO_INT_TWIPS(x)     NSToIntRound(NS_POINTS_TO_TWIPS(x))
 478 #define NS_INCHES_TO_INT_TWIPS(x)     NSToIntRound(NS_INCHES_TO_TWIPS(x))
 479
 480 #define NS_TWIPS_TO_POINTS(x)         NSTwipsToUnits((x), 1.0f)
 481 #define NS_TWIPS_TO_INCHES(x)         NSTwipsToUnits((x), 1.0f / POINTS_PER_INCH_FLOAT)
 482
 483 #define NS_TWIPS_TO_MILLIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.03937f))
 484 #define NS_TWIPS_TO_CENTIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.3937f))
 485
 486 #define NS_TWIPS_TO_PICAS(x)          NSTwipsToUnits((x), 1.0f / 12.0f)
 487 //@}
 488
 489 #endif /* NSCOORD_H */