gls_util.h

Go to the documentation of this file.

#ifndef _GLS_UTIL_H
#define _GLS_UTIL_H

/*! \file gls_util.h

\brief  This header defines general utility classes, functions and macros 
        in the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_types.h"
#include "gls_color.h"
#include "gls_vertex.h"
#include "gls_class_invariant.h"

// forward refs
struct GlsVector3D;

/** maximum value macro */
#define GLS_MAX( _a, _b )   ( ( (_a) > (_b) ) ? (_a) : (_b) )

/** A collection of utility classes and functions
  * \invariant NA (all static members)
  */
class GlsUtil
{
public:
    /** PI constant */
    static const GlsFloat64 PI;
    /** degrees to radians conversion factor */
    static const GlsFloat64 DEGREES_TO_RADIANS;

    /** black GlsColor constant */
    static const GlsColor BLACK_GLS_COLOR;

    /** 3D vector of all zeroes */
    static const GlsVector3D ZERO_VECTOR_3D;
    /** 3D vector of all ones */
    static const GlsVector3D ONE_VECTOR_3D;

    /** helper class for reading data in inline format
      * \invariant _inlineData != GLS_NULL, _inlineDataLength > 0u,
      *            _lineLength > 0u, _curLineIndex < _lineLength,
      *            _numBytesRead <= _inlineDataLength
      */
    class InlineReader
    {
    public:
        GLS_CLASS_INVARIANT_DECLARATION( InlineReader )

        /** Constructor
          * \param inlineData inline data
          * \param inlineDataLength number of bytes in inline data (not including NULL terminators)
          * \param lineLength length (in bytes) of one line of data in the inline data (not including NULL terminator)
          * \pre inlineData != GLS_NULL, inlineDataLength > 0, lineLength > 0
          * \post instance constructed
          */
        InlineReader( const GlsUChar* const inlineData[], const GlsUInt32 inlineDataLength,
                      const GlsUInt32 lineLength );

        /** Destructor
          * \pre none
          * \post instance destroyed
          */
        ~InlineReader();

        /** Read a byte from the inline data
          * \return one byte read from inline data
          * \pre there must be at least one byte of inline data left to read
          * \post one byte is read from the inline data
          */
        GlsUChar ReadByte( void );

        /** Determine if the reader has read all of its inline data
          * \return GLS_TRUE if reader has read all of its inline data else GLS_FALSE
          * \pre none
          * \post none
          */
        GlsBool IsDone( void ) const;

    protected:
        const GlsUChar* const *_inlineData;       /**< inline data to read */
        const GlsUInt32        _inlineDataLength; /**< number of bytes in inline data
                                                    * (not including NULL terminators) */
        const GlsUInt32        _lineLength;       /**< length (in bytes) of one line of data in the inline data
                                                    * (not including NULL terminator) */

        GlsUInt32              _curLine;          /**< index to current line of inline data */
        GlsUInt32              _curLineIndex;     /**< index to current byte of current line */
        GlsUInt32              _numBytesRead;     /**< number of bytes read from inline data */

    private:
        // Disable implicit generated Members
        InlineReader& operator=( const InlineReader &rhs );
        InlineReader( const InlineReader &src );
    };

    /** Determine if the given value is very close (< 10E-4) to 0.0
      * \param val value in question
      * \return GLS_TRUE if very close to zero else GLS_FALSE
      * \pre GlsFloatIsValid( val );
      * \post none
      */
    static GlsBool VeryCloseToZero( const GlsFloat32 val );

    /** Determine if the two given floats are within precision amount of each other
      * \param x first float in question
      * \param y second float in question
      * \param precision precision amount indicating equal floats
      * \return GLS_TRUE if the two floats are within precision of each other else GLS_FALSE
      * \pre GlsFloatIsValid( x ), GlsFloatIsValid( y ), GlsFloatIsValid( precision ), precision > 0.0
      * \post none
      */
    static GlsBool EqualFloat32( const GlsFloat32 x, const GlsFloat32 y, const GlsFloat32 precision );

    /** Get the gloating point modulus ( x mod y )
      * \param x number to mod
      * \param y number to mod by
      * \return x mod y
      * \pre GlsFloatIsValid( x ), GlsFloatIsValid( y )
      * \post none
      */
    static GlsFloat64 Float64Mod( const GlsFloat64 x, const GlsFloat64 y );

    /** Determine if the two given colors are equal
      * \param a first color in question
      * \param b second color in question
      * \return GLS_TRUE if the colors are equal else GLS_FALSE
      * \pre a.IsValid(), b.IsValid()
      * \post none
      */
    static GlsBool EqualColor( const GlsColor &a, const GlsColor &b );

    /** Normalize the given vector
      * \param v [in/out] vector to normalize
      * \pre v.IsValid(), the magnitide of v > 0.0
      * \post v is normalized
      */
    static void NormalizeVector3D( GlsVector3D &v );

    /** Compute the 3D vector cross product of the the two vectors, assigning
      * the result to v.
      * \param v [in/out] vector on left side of cross product, receives result of  cross product computation
      * \param w right side of cross product
      * \pre v.IsValid(), w.IsValid();
      * \post v = v X w
      */
    static void CrossProductVector3D( GlsVector3D &v, const GlsVector3D &w );

    /** Compute the distance between the two given 3D points
      * \param v first 3D point
      * \param w second 3D point
      * \return distance from v to w
      * \pre v.IsValid(), w.IsValid()
      * \post none
      */
    static GlsFloat32 DistanceVector3D( const GlsVector3D &v, const GlsVector3D &w );

protected:
    /** value used to determine if a value is close to 0.0 */
    static const GlsFloat32 CLOSE_TO_ZERO;
};

#endif // GLS_UTIL_H