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 NSToCoordCeil(float aValue)
 289 {
 290   return nscoord(NS_ceilf(aValue));
 291 }
 292
 293 inline nscoord NSToCoordRound(float aValue)
 294 {
 295 #if defined(XP_WIN32) && defined(_M_IX86) && !defined(__GNUC__)
 296   return NS_lroundup30(aValue);
 297 #else
 298   return nscoord(NS_floorf(aValue + 0.5f));
 299 #endif /* XP_WIN32 && _M_IX86 && !__GNUC__ */
 300 }
 301
 302 /*
 303  * Int Rounding Functions
 304  */
 305 inline PRInt32 NSToIntFloor(float aValue)
 306 {
 307   return PRInt32(NS_floorf(aValue));
 308 }
 309
 310 inline PRInt32 NSToIntCeil(float aValue)
 311 {
 312   return PRInt32(NS_ceilf(aValue));
 313 }
 314
 315 inline PRInt32 NSToIntRound(float aValue)
 316 {
 317   return NS_lroundf(aValue);
 318 }
 319
 320 /*
 321  * App Unit/Pixel conversions
 322  */
 323 inline nscoord NSFloatPixelsToAppUnits(float aPixels, PRInt32 aAppUnitsPerPixel)
 324 {
 325   float product = aPixels * aAppUnitsPerPixel;
 326   nscoord result;
 327
 328 #ifdef NS_COORD_IS_FLOAT
 329   // No need to bounds-check if converting float to float
 330   result = NSToCoordRound(product);
 331 #else
 332   // Bounds-check before converting out of float, to avoid overflow
 333   if (product >= nscoord_MAX) {
 334     NS_WARNING("Overflowed nscoord_MAX in conversion to nscoord");
 335     result = nscoord_MAX;
 336   } else if (product <= nscoord_MIN) {
 337     NS_WARNING("Overflowed nscoord_MIN in conversion to nscoord");
 338     result = nscoord_MIN;
 339   } else {
 340     result = NSToCoordRound(product);
 341   }
 342 #endif
 343
 344   VERIFY_COORD(result);
 345   return result;
 346 }
 347
 348 inline nscoord NSIntPixelsToAppUnits(PRInt32 aPixels, PRInt32 aAppUnitsPerPixel)
 349 {
 350   // The cast to nscoord makes sure we don't overflow if we ever change
 351   // nscoord to float
 352   nscoord r = aPixels * (nscoord)aAppUnitsPerPixel;
 353   VERIFY_COORD(r);
 354   return r;
 355 }
 356
 357 inline float NSAppUnitsToFloatPixels(nscoord aAppUnits, PRInt32 aAppUnitsPerPixel)
 358 {
 359   return (float(aAppUnits) / aAppUnitsPerPixel);
 360 }
 361
 362 inline PRInt32 NSAppUnitsToIntPixels(nscoord aAppUnits, PRInt32 aAppUnitsPerPixel)
 363 {
 364   return NSToIntRound(float(aAppUnits) / aAppUnitsPerPixel);
 365 }
 366
 367 /// handy constants
 368 #define TWIPS_PER_POINT_INT           20
 369 #define TWIPS_PER_POINT_FLOAT         20.0f
 370 #define POINTS_PER_INCH_INT           72
 371 #define POINTS_PER_INCH_FLOAT         72.0f
 372
 373 /*
 374  * Twips/unit conversions
 375  */
 376 inline nscoord NSUnitsToTwips(float aValue, float aPointsPerUnit)
 377 {
 378   return NSToCoordRound(aValue * aPointsPerUnit * TWIPS_PER_POINT_FLOAT);
 379 }
 380
 381 inline float NSTwipsToUnits(nscoord aTwips, float aUnitsPerPoint)
 382 {
 383   return (aTwips * (aUnitsPerPoint / TWIPS_PER_POINT_FLOAT));
 384 }
 385
 386
 387 /// Unit conversion macros
 388 //@{
 389 #define NS_POINTS_TO_TWIPS(x)         NSUnitsToTwips((x), 1.0f)
 390 #define NS_INCHES_TO_TWIPS(x)         NSUnitsToTwips((x), POINTS_PER_INCH_FLOAT)                      // 72 points per inch
 391 #define NS_FEET_TO_TWIPS(x)           NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 12.0f))            // 12 inches per foot
 392 #define NS_MILES_TO_TWIPS(x)          NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 12.0f * 5280.0f))  // 5280 feet per mile
 393
 394 #define NS_MILLIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.03937f))
 395 #define NS_CENTIMETERS_TO_TWIPS(x)    NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 0.3937f))
 396 #define NS_METERS_TO_TWIPS(x)         NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 39.37f))
 397 #define NS_KILOMETERS_TO_TWIPS(x)     NSUnitsToTwips((x), (POINTS_PER_INCH_FLOAT * 39370.0f))
 398
 399 #define NS_PICAS_TO_TWIPS(x)          NSUnitsToTwips((x), 12.0f)                      // 12 points per pica
 400 #define NS_DIDOTS_TO_TWIPS(x)         NSUnitsToTwips((x), (16.0f / 15.0f))            // 15 didots per 16 points
 401 #define NS_CICEROS_TO_TWIPS(x)        NSUnitsToTwips((x), (12.0f * (16.0f / 15.0f)))  // 12 didots per cicero
 402
 403 #define NS_TWIPS_TO_POINTS(x)         NSTwipsToUnits((x), 1.0f)
 404 #define NS_TWIPS_TO_INCHES(x)         NSTwipsToUnits((x), 1.0f / POINTS_PER_INCH_FLOAT)
 405 #define NS_TWIPS_TO_FEET(x)           NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 12.0f))
 406 #define NS_TWIPS_TO_MILES(x)          NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 12.0f * 5280.0f))
 407
 408 #define NS_TWIPS_TO_MILLIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.03937f))
 409 #define NS_TWIPS_TO_CENTIMETERS(x)    NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 0.3937f))
 410 #define NS_TWIPS_TO_METERS(x)         NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 39.37f))
 411 #define NS_TWIPS_TO_KILOMETERS(x)     NSTwipsToUnits((x), 1.0f / (POINTS_PER_INCH_FLOAT * 39370.0f))
 412
 413 #define NS_TWIPS_TO_PICAS(x)          NSTwipsToUnits((x), 1.0f / 12.0f)
 414 #define NS_TWIPS_TO_DIDOTS(x)         NSTwipsToUnits((x), 1.0f / (16.0f / 15.0f))
 415 #define NS_TWIPS_TO_CICEROS(x)        NSTwipsToUnits((x), 1.0f / (12.0f * (16.0f / 15.0f)))
 416 //@}
 417
 418 #endif /* NSCOORD_H */