gfx/public/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/idl/gfxtypes.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 NSCoordMultiply(nscoord aCoord, float aVal) {
  92   VERIFY_COORD(aCoord);
  93 #ifdef NS_COORD_IS_FLOAT
  94   return floorf(aCoord*aVal);
  95 #else
  96   return (PRInt32)(aCoord*aVal);
  97 #endif
  98 }
  99
 100 inline nscoord NSCoordMultiply(nscoord aCoord, PRInt32 aVal) {
 101   VERIFY_COORD(aCoord);
 102   return aCoord*aVal;
 103 }
 104
 105 inline nscoord NSCoordDivide(nscoord aCoord, float aVal) {
 106   VERIFY_COORD(aCoord);
 107 #ifdef NS_COORD_IS_FLOAT
 108   return floorf(aCoord/aVal);
 109 #else
 110   return (PRInt32)(aCoord/aVal);
 111 #endif
 112 }
 113
 114 inline nscoord NSCoordDivide(nscoord aCoord, PRInt32 aVal) {
 115   VERIFY_COORD(aCoord);
 116 #ifdef NS_COORD_IS_FLOAT
 117   return floorf(aCoord/aVal);
 118 #else
 119   return aCoord/aVal;
 120 #endif
 121 }
 122
 123 /**
 124  * Returns a + b, capping the sum to nscoord_MAX.
 125  *
 126  * This function assumes that neither argument is nscoord_MIN.
 127  *
 128  * Note: If/when we start using floats for nscoords, this function won't be as
 129  * necessary.  Normal float addition correctly handles adding with infinity,
 130  * assuming we aren't adding nscoord_MIN. (-infinity)
 131  */
 132 inline nscoord
 133 NSCoordSaturatingAdd(nscoord a, nscoord b)
 134 {
 135   VERIFY_COORD(a);
 136   VERIFY_COORD(b);
 137   NS_ASSERTION(a != nscoord_MIN && b != nscoord_MIN,
 138                "NSCoordSaturatingAdd got nscoord_MIN as argument");
 139
 140 #ifdef NS_COORD_IS_FLOAT
 141   // Float math correctly handles a+b, given that neither is -infinity.
 142   return a + b;
 143 #else
 144   if (a == nscoord_MAX || b == nscoord_MAX) {
 145     // infinity + anything = anything + infinity = infinity
 146     return nscoord_MAX;
 147   } else {
 148     // a + b = a + b
 149     NS_ASSERTION(a < nscoord_MAX && b < nscoord_MAX,
 150                  "Doing nscoord addition with values > nscoord_MAX");
 151     NS_ASSERTION((PRInt64)a + (PRInt64)b > (PRInt64)nscoord_MIN,
 152                  "nscoord addition will reach or pass nscoord_MIN");
 153     // This one's only a warning because the PR_MIN below means that
 154     // we'll handle this case correctly.
 155     NS_WARN_IF_FALSE((PRInt64)a + (PRInt64)b < (PRInt64)nscoord_MAX,
 156                      "nscoord addition capped to nscoord_MAX");
 157
 158     // Cap the result, just in case we're dealing with numbers near nscoord_MAX
 159     return PR_MIN(nscoord_MAX, a + b);
 160   }
 161 #endif
 162 }
 163
 164 /**
 165  * Returns a - b, gracefully handling cases involving nscoord_MAX.
 166  * This function assumes that neither argument is nscoord_MIN.
 167  *
 168  * The behavior is as follows:
 169  *
 170  *  a)  infinity - infinity -> infMinusInfResult
 171  *  b)  N - infinity        -> 0  (unexpected -- triggers NOTREACHED)
 172  *  c)  infinity - N        -> infinity
 173  *  d)  N1 - N2             -> N1 - N2
 174  *
 175  * Note: For float nscoords, cases (c) and (d) are handled by normal float
 176  * math.  We still need to explicitly specify the behavior for cases (a)
 177  * and (b), though.  (Under normal float math, those cases would return NaN
 178  * and -infinity, respectively.)
 179  */
 180 inline nscoord
 181 NSCoordSaturatingSubtract(nscoord a, nscoord b,
 182                           nscoord infMinusInfResult)
 183 {
 184   VERIFY_COORD(a);
 185   VERIFY_COORD(b);
 186   NS_ASSERTION(a != nscoord_MIN && b != nscoord_MIN,
 187                "NSCoordSaturatingSubtract got nscoord_MIN as argument");
 188
 189   if (b == nscoord_MAX) {
 190     if (a == nscoord_MAX) {
 191       // case (a)
 192       return infMinusInfResult;
 193     } else {
 194       // case (b)
 195       NS_NOTREACHED("Attempted to subtract [n - nscoord_MAX]");
 196       return 0;
 197     }
 198   } else {
 199 #ifdef NS_COORD_IS_FLOAT
 200     // case (c) and (d) for floats.  (float math handles both)
 201     return a - b;
 202 #else
 203     if (a == nscoord_MAX) {
 204       // case (c) for integers
 205       return nscoord_MAX;
 206     } else {
 207       // case (d) for integers
 208       NS_ASSERTION(a < nscoord_MAX && b < nscoord_MAX,
 209                    "Doing nscoord subtraction with values > nscoord_MAX");
 210       NS_ASSERTION((PRInt64)a - (PRInt64)b > (PRInt64)nscoord_MIN,
 211                    "nscoord subtraction will reach or pass nscoord_MIN");
 212       // This one's only a warning because the PR_MIN below means that
 213       // we'll handle this case correctly.
 214       NS_WARN_IF_FALSE((PRInt64)a - (PRInt64)b < (PRInt64)nscoord_MAX,
 215                        "nscoord subtraction capped to nscoord_MAX");
 216
 217       // Cap the result, in case we're dealing with numbers near nscoord_MAX
 218       return PR_MIN(nscoord_MAX, a - b);
 219     }
 220   }
 221 #endif
 222 }
 223 /** compare against a nscoord "b", which might be unconstrained
 224   * "a" must not be unconstrained.
 225   * Every number is smaller than a unconstrained one
 226   */
 227 inline PRBool
 228 NSCoordLessThan(nscoord a,nscoord b)
 229 {
 230   NS_ASSERTION(a != nscoord_MAX,
 231                "This coordinate should be constrained");
 232   return ((a < b) || (b == nscoord_MAX));
 233 }
 234
 235 /** compare against a nscoord "b", which might be unconstrained
 236   * "a" must not be unconstrained
 237   * No number is larger than a unconstrained one.
 238   */
 239 inline PRBool
 240 NSCoordGreaterThan(nscoord a,nscoord b)
 241 {
 242   NS_ASSERTION(a != nscoord_MAX,
 243                "This coordinate should be constrained");
 244   return ((a > b) && (b != nscoord_MAX));
 245 }
 246
 247 /**
 248  * Convert an nscoord to a PRInt32. This *does not* do rounding because
 249  * coords are never fractional. They can be out of range, so this does
 250  * clamp out of bounds coord values to PR_INT32_MIN and PR_INT32_MAX.
 251  */
 252 inline PRInt32 NSCoordToInt(nscoord aCoord) {
 253   VERIFY_COORD(aCoord);
 254 #ifdef NS_COORD_IS_FLOAT
 255   NS_ASSERTION(!NS_IEEEIsNan(aCoord), "NaN encountered in int conversion");
 256   if (aCoord < -2147483648.0f) {
 257     // -2147483648 is the smallest 32-bit signed integer that can be
 258     // exactly represented as a float
 259     return PR_INT32_MIN;
 260   } else if (aCoord > 2147483520.0f) {
 261     // 2147483520 is the largest 32-bit signed integer that can be
 262     // exactly represented as an IEEE float
 263     return PR_INT32_MAX;
 264   } else {
 265     return (PRInt32)aCoord;
 266   }
 267 #else
 268   return aCoord;
 269 #endif
 270 }
 271
 272 inline float NSCoordToFloat(nscoord aCoord) {
 273   VERIFY_COORD(aCoord);
 274 #ifdef NS_COORD_IS_FLOAT
 275   NS_ASSERTION(!NS_IEEEIsNan(aCoord), "NaN encountered in float conversion");
 276 #endif
 277   return (float)aCoord;
 278 }
 279
 280 /*
 281  * Coord Rounding Functions
 282  */
 283 inline nscoord NSToCoordFloor(float aValue)
 284 {
 285   return nscoord(NS_floorf(aValue));
 286 }
 287
 288 inline nscoord NSToCoordFloorClamped(float aValue)
 289 {
 290 #ifndef NS_COORD_IS_FLOAT
 291   // Bounds-check before converting out of float, to avoid overflow
 292   if (aValue >= nscoord_MAX) {
 293     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 294     return nscoord_MAX;
 295   }
 296   if (aValue <= nscoord_MIN) {
 297     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 298     return nscoord_MIN;
 299   }
 300 #endif
 301   return NSToCoordFloor(aValue);
 302 }
 303
 304 inline nscoord NSToCoordCeil(float aValue)
 305 {
 306   return nscoord(NS_ceilf(aValue));
 307 }
 308
 309 inline nscoord NSToCoordCeilClamped(float aValue)
 310 {
 311 #ifndef NS_COORD_IS_FLOAT
 312   // Bounds-check before converting out of float, to avoid overflow
 313   if (aValue >= nscoord_MAX) {
 314     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 315     return nscoord_MAX;
 316   }
 317   if (aValue <= nscoord_MIN) {
 318     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 319     return nscoord_MIN;
 320   }
 321 #endif
 322   return NSToCoordCeil(aValue);
 323 }
 324
 325 inline nscoord NSToCoordRound(float aValue)
 326 {
 327 #if defined(XP_WIN32) && defined(_M_IX86) && !defined(__GNUC__)
 328   return NS_lroundup30(aValue);
 329 #else
 330   return nscoord(NS_floorf(aValue + 0.5f));
 331 #endif /* XP_WIN32 && _M_IX86 && !__GNUC__ */
 332 }
 333
 334 inline nscoord NSToCoordRoundWithClamp(float aValue)
 335 {
 336 #ifndef NS_COORD_IS_FLOAT
 337   // Bounds-check before converting out of float, to avoid overflow
 338   if (aValue >= nscoord_MAX) {
 339     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 340     return nscoord_MAX;
 341   }
 342   if (aValue <= nscoord_MIN) {
 343     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 344     return nscoord_MIN;
 345   }
 346 #endif
 347   return NSToCoordRound(aValue);
 348 }
 349
 350 /*
 351  * Int Rounding Functions
 352  */
 353 inline PRInt32 NSToIntFloor(float aValue)
 354 {
 355   return PRInt32(NS_floorf(aValue));
 356 }
 357
 358 inline PRInt32 NSToIntCeil(float aValue)
 359 {
 360   return PRInt32(NS_ceilf(aValue));
 361 }
 362
 363 inline PRInt32 NSToIntRound(float aValue)
 364 {
 365   return NS_lroundf(aValue);
 366 }
 367
 368 /*
 369  * App Unit/Pixel conversions
 370  */
 371 inline nscoord NSFloatPixelsToAppUnits(float aPixels, float aAppUnitsPerPixel)
 372 {
 373   return NSToCoordRoundWithClamp(aPixels * aAppUnitsPerPixel);
 374 }
 375
 376 inline nscoord NSIntPixelsToAppUnits(PRInt32 aPixels, PRInt32 aAppUnitsPerPixel)
 377 {
 378   // The cast to nscoord makes sure we don't overflow if we ever change
 379   // nscoord to float
 380   nscoord r = aPixels * (nscoord)aAppUnitsPerPixel;
 381   VERIFY_COORD(r);
 382   return r;
 383 }
 384
 385 inline float NSAppUnitsToFloatPixels(nscoord aAppUnits, float aAppUnitsPerPixel)
 386 {
 387   return (float(aAppUnits) / aAppUnitsPerPixel);
 388 }
 389
 390 inline PRInt32 NSAppUnitsToIntPixels(nscoord aAppUnits, float aAppUnitsPerPixel)
 391 {
 392   return NSToIntRound(float(aAppUnits) / aAppUnitsPerPixel);
 393 }
 394
 395 /// handy constants
 396 #define TWIPS_PER_POINT_INT           20
 397 #define TWIPS_PER_POINT_FLOAT         20.0f
 398 #define POINTS_PER_INCH_INT           72
 399 #define POINTS_PER_INCH_FLOAT         72.0f
 400
 401 /*
 402  * Twips/unit conversions
 403  */
 404 inline nscoord NSUnitsToTwips(float aValue, float aPointsPerUnit)
 405 {
 406   return NSToCoordRound(aValue * aPointsPerUnit * TWIPS_PER_POINT_FLOAT);
 407 }
 408
 409 inline float NSTwipsToUnits(nscoord aTwips, float aUnitsPerPoint)
 410 {
 411   return (aTwips * (aUnitsPerPoint / TWIPS_PER_POINT_FLOAT));
 412 }
 413
 414
 415 /// Unit conversion macros
 416 //@{
 417 #define NS_POINTS_TO_TWIPS(x)         NSUnitsToTwips((x), 1.0f)
 418 #define NS_INCHES_TO_TWIPS(x)         NSUnitsToTwips((x), POINTS_PER_INCH_FLOAT)                      // 72 points per inch
 419 #define NS_FEET_TO_TWIPS(x)           NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 12.0f))            // 12 inches per foot
 420 #define NS_MILES_TO_TWIPS(x)          NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 12.0f * 5280.0f))  // 5280 feet per mile
 421
 422 #define NS_MILLIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.03937f))
 423 #define NS_CENTIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.3937f))
 424 #define NS_METERS_TO_TWIPS(x)         NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 39.37f))
 425 #define NS_KILOMETERS_TO_TWIPS(x)     NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 39370.0f))
 426
 427 #define NS_PICAS_TO_TWIPS(x)          NSUnitsToTwips((x), 12.0f)                      // 12 points per pica
 428 #define NS_DIDOTS_TO_TWIPS(x)         NSUnitsToTwips((x), (16.0f / 15.0f))            // 15 didots per 16 points
 429 #define NS_CICEROS_TO_TWIPS(x)        NSUnitsToTwips((x), (12.0f * (16.0f / 15.0f)))  // 12 didots per cicero
 430
 431 #define NS_TWIPS_TO_POINTS(x)         NSTwipsToUnits((x), 1.0f)
 432 #define NS_TWIPS_TO_INCHES(x)         NSTwipsToUnits((x), 1.0f / POINTS_PER_INCH_FLOAT)
 433 #define NS_TWIPS_TO_FEET(x)           NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 12.0f))
 434 #define NS_TWIPS_TO_MILES(x)          NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 12.0f * 5280.0f))
 435
 436 #define NS_TWIPS_TO_MILLIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.03937f))
 437 #define NS_TWIPS_TO_CENTIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.3937f))
 438 #define NS_TWIPS_TO_METERS(x)         NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 39.37f))
 439 #define NS_TWIPS_TO_KILOMETERS(x)     NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 39370.0f))
 440
 441 #define NS_TWIPS_TO_PICAS(x)          NSTwipsToUnits((x), 1.0f / 12.0f)
 442 #define NS_TWIPS_TO_DIDOTS(x)         NSTwipsToUnits((x), 1.0f / (16.0f / 15.0f))
 443 #define NS_TWIPS_TO_CICEROS(x)        NSTwipsToUnits((x), 1.0f / (12.0f * (16.0f / 15.0f)))
 444 //@}
 445
 446 #endif /* NSCOORD_H */