dox/Common/Math/vtkFastNumericConversion.h

Go to the documentation of this file.

/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkFastNumericConversion.h

  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
#ifndef __vtkFastNumericConversion_h
#define __vtkFastNumericConversion_h

#include "vtkCommonMathModule.h" // For export macro
#include "vtkObject.h"

// Use the bit-representation trick only on X86, and only when producing
// optimized code
#if defined(NDEBUG) && (defined i386 || defined _M_IX86)
#define VTK_USE_TRICK
#endif

// Linux puts the FPU in extended precision. Windows and FreeBSD keep it in
// double precision.  If other operating systems for i386 (Solaris?) behave
// like Linux, add them below.  Special care needs to be taken when dealing
// with extended precision mode because even though we are eventually writing
// out to a double-precision variable to capture the fixed-point or integer
// results, the extra bits maintained in the internal computations disrupt
// the bit-playing that we're doing here.
#if defined(__linux__)
#define VTK_EXT_PREC
#endif

//#define VTK_TEST_HACK_TO_EMULATE_LINUX_UNDER_WINDOWS
#ifdef VTK_TEST_HACK_TO_EMULATE_LINUX_UNDER_WINDOWS
#define VTK_EXT_PREC
#endif


class VTKCOMMONMATH_EXPORT vtkFastNumericConversion : public vtkObject
{
public:
  static vtkFastNumericConversion *New();
  vtkTypeMacro(vtkFastNumericConversion, vtkObject);
  void PrintSelf(ostream& os, vtkIndent indent);

  int TestQuickFloor(double val)
    {
    return vtkFastNumericConversion::QuickFloor(val);
    }

  int TestSafeFloor(double val)
    {
    return vtkFastNumericConversion::SafeFloor(val);
    }

  int TestRound(double val)
    {
    return vtkFastNumericConversion::Round(val);
    }

  int TestConvertFixedPointIntPart(double val)
    {
    int frac;
    return ConvertFixedPoint(val, frac);
    }

  int TestConvertFixedPointFracPart(double val)
    {
    int frac;
    ConvertFixedPoint(val, frac);
    return frac;
    }

protected:
  //BTX
  static inline double BorrowBit() { return 1.5;};


  static inline double two30()
    {
      return static_cast<double>(static_cast<unsigned long>(1) << 30);
    }


  static inline double two52()
    {
      return (static_cast<unsigned long>(1) << (52-30)) * two30();
    }


  static inline double two51()
    {
      return (static_cast<unsigned long>(1) << (51-30)) * two30();
    }


  static inline double two63()
    {
      return (static_cast<unsigned long>(1) << (63-60)) * two30() * two30();
    }


  static inline double two62()
    {
      return (static_cast<unsigned long>(1) << (62-60)) * two30() * two30();
    }

  // Define number of bits of precision for various data types.
  // Note: INT_BITS is really 31, (rather than 32, since one of the bits is
  // just used for the two's-complement sign), but we say 30 because we don't
  // need to be able to handle 31-bit magnitudes correctly. I say that
  // because this is used for the QuickFloor code, and the SafeFloor code
  // retains an extra bit of fixed point precision which it shifts-out at the
  // end, thus reducing the magnitude of integers that it can handle. That's
  // an inherent limitation of using SafeFloor to prevent round-ups under any
  // circumstances, and there's no need to make QuickFloor handle a wider
  // range of numbers than SafeFloor.
#define INT_BITS 30
#define EXT_BITS 64
#define DBL_BITS 53


public:
#ifdef VTK_EXT_PREC
  // Compute (0.5 ^ (EXT_BITS-INT_BITS)) as a compile-time constant
  static inline double RoundingTieBreaker()
    {
      return 1.0 / (two30() * (static_cast<unsigned long>(1) << (EXT_BITS - INT_BITS - 30)));
    }
#else
  // Compute (0.5 ^ (DBL_BITS-INT_BITS)) as a compile-time constant
  static inline double RoundingTieBreaker()
    {
      return 1.0 / (static_cast<unsigned long>(1) << (DBL_BITS - INT_BITS));
    }
#endif


protected:

  static inline double QuickFloorDenormalizer()
    {return two52() * BorrowBit(); };


  static inline double SafeFloorDenormalizer()
    { return two51() * BorrowBit(); };


  static inline double QuickExtPrecTempDenormalizer()
    {return two63() * BorrowBit(); };


  static inline double SafeExtPrecTempDenormalizer()
    {return two62() * BorrowBit(); };

  static inline double QuickRoundAdjust() {return 0.5;};
  static inline double SafeRoundAdjust() {return 0.25;};
  static inline int SafeFinalShift() {return 1;};


#ifdef VTK_WORDS_BIGENDIAN
  enum {exponent_pos = 0, mantissa_pos = 1};
#else
  enum {exponent_pos = 1, mantissa_pos = 0};
#endif
  //ETX

public:


  void SetReservedFracBits(int bits)
    {
    // Add one to the requested number of fractional bits, to make
    // the conversion safe with respect to rounding mode. This is the
    // same as the difference between QuickFloor and SafeFloor.
    bits++;
    unsigned long mtime = this->GetMTime();
    this->SetinternalReservedFracBits(bits);
    if (mtime != this->GetMTime())
      {
      this->InternalRebuild();
      }
    };

  //BTX
  static int QuickFloor(const double &val);

  static int SafeFloor(const double &val);

  static int Round(const double &val);


  inline int ConvertFixedPoint(const double &val, int &fracPart)
    {
      union { int i[2]; double d; } u;
#ifdef VTK_EXT_PREC
      u.d = (((val - fixRound)
              + this->epTempDenormalizer)
             - this->epTempDenormalizer)
        + this->fpDenormalizer;
#else // ! VTK_EXT_PREC
      u.d = (val - fixRound)
        + this->fpDenormalizer;
#endif // VTK_EXT_PREC
    fracPart = (u.i[mantissa_pos] & fracMask) >> 1;
    return u.i[mantissa_pos] >> this->internalReservedFracBits;
    }
  //ETX


protected:
  //BTX
  vtkFastNumericConversion();
  ~vtkFastNumericConversion() {};
  void InternalRebuild(void);

private:
  vtkSetMacro(internalReservedFracBits, int);
  vtkGetMacro(internalReservedFracBits, int);

#ifndef VTK_LEGACY_SILENT
  static int QuickFloorInline(const double &val);
  static int SafeFloorInline(const double &val);
  static int RoundInline(const double &val);
#endif

  int internalReservedFracBits;
  int fracMask;

  // Used when doing fixed point conversions with a certain number of bits
  // remaining for the fractional part, as opposed to the pure integer
  // flooring
  double fpDenormalizer;

  // Used when doing fixed point conversions in extended precision mode
  double epTempDenormalizer;

  // Adjustment for rounding based on the number of bits reserved for
  // fractional representation
  double fixRound;
  //ETX

  vtkFastNumericConversion(const vtkFastNumericConversion&); // Not implemented
  void operator=(const vtkFastNumericConversion&); // Not implemented
};

#ifndef VTK_LEGACY_SILENT
inline int vtkFastNumericConversion::QuickFloorInline(const double &val)
#else
inline int vtkFastNumericConversion::QuickFloor(const double &val)
#endif
{
#ifdef VTK_USE_TRICK
  union { int i[2]; double d; } u;
#ifdef VTK_EXT_PREC
  u.d = (((val - (QuickRoundAdjust() - RoundingTieBreaker()))
          // Push off those extended precision bits
          + QuickExtPrecTempDenormalizer())
         // Pull back the wanted bits into double range
         - QuickExtPrecTempDenormalizer())
    + QuickFloorDenormalizer();
#else // ! VTK_EXT_PREC
  u.d = (val - (QuickRoundAdjust() - RoundingTieBreaker()))
    + QuickFloorDenormalizer();
#endif // VTK_EXT_PREC
  return u.i[mantissa_pos];
#else // ! VTK_USE_TRICK
  return static_cast<int>(val);
#endif // VTK_USE_TRICK
}

#ifndef VTK_LEGACY_SILENT
inline int vtkFastNumericConversion::SafeFloorInline(const double &val)
#else
inline int vtkFastNumericConversion::SafeFloor(const double &val)
#endif
{
#ifdef VTK_USE_TRICK
  union { int i[2]; double d; } u;
#ifdef VTK_EXT_PREC
  u.d = (((val - SafeRoundAdjust())
          + SafeExtPrecTempDenormalizer())
         - SafeExtPrecTempDenormalizer())
    + SafeFloorDenormalizer();
#else // ! VTK_EXT_PREC
  u.d = (val - SafeRoundAdjust())
    + SafeFloorDenormalizer();
#endif // VTK_EXT_PREC
  return u.i[mantissa_pos] >> SafeFinalShift();
#else // ! VTK_USE_TRICK
  return static_cast<int>(val);
#endif // VTK_USE_TRICK
}

#ifndef VTK_LEGACY_SILENT
inline int vtkFastNumericConversion::RoundInline(const double &val)
#else
inline int vtkFastNumericConversion::Round(const double &val)
#endif
{
#ifdef VTK_USE_TRICK
  union { int i[2]; double d; } u;
#ifdef VTK_EXT_PREC
  u.d = ((val
          + QuickExtPrecTempDenormalizer())
         - QuickExtPrecTempDenormalizer())
    + QuickFloorDenormalizer();
#else // ! VTK_EXT_PREC
  u.d = val
    + QuickFloorDenormalizer();
#endif // VTK_EXT_PREC
return u.i[mantissa_pos];
#else // ! VTK_USE_TRICK
if (val>=0)
  {
  return static_cast<int>(val + 0.5);
  }
else
  {
  return static_cast<int>(val - 0.5);
  }
#endif // VTK_USE_TRICK
}

#endif