util.h

Go to the documentation of this file.

/*! \file
  \brief  Generally useful defines, macros, enumerations and function
          prototypes.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef INCLUDED_GLS_RUNTIME_UTIL_H
#define INCLUDED_GLS_RUNTIME_UTIL_H

#include "ConvertUTF.h"
#include "disti_assert.h"
#include "dynamic_array.h"
#include "gls_cpp_lang_support.h"
#include "gls_include.h"
#include "gls_matrix_affine.h"
#include "scoped_ptr.h"
#include "unhide_globals.h"
#include "vertex.h"

#include <algorithm>
#include <cmath>
#include <iostream>
#include <sstream>
#include <string>
#include <typeinfo>
#include <vector>

#ifdef WIN32
#    include <direct.h>
#else
#    include <unistd.h>
#endif

#if defined( QNX )
#    include <stdio.h>
#else
#    include <cstdio>
#endif

#if defined( LINUX ) || defined( __VXWORKS__ ) || defined( __APPLE__ ) || defined( QNX )
#    include <strings.h>
#endif

#ifdef ANDROID
#    include <android/asset_manager.h>
#endif

const int DIALOG_MAX_DIRECTORY_LENGTH = 1024; // Limited by FLTK FileBrowser

class Fl_Window;

// Wrap code that should only be compiled in debug in GLS_DEBUG_CODE()
#if defined( GLS_DEBUG ) || !defined( NDEBUG )
#    define GLS_DEBUG_CODE( x ) x
#else
#    define GLS_DEBUG_CODE( x )
#endif

namespace disti
{
class Vertex;
class DisplayObject;
class DisplayFrame;

#ifndef TRUE
#    define TRUE 1
#endif

#ifndef FALSE
#    define FALSE 0
#endif

#ifdef WIN32
inline int strcasecmp( const char* const x, const char* const y )
{
    return _stricmp( x, y );
}
#endif

/** Used to generate inline textures.  The writing and reading of the lines need to know the length. */
const int INLINE_TEXTURE_LINE_LENGTH = 240;

/* Used for parsing lines of clear text */
const char PARSER_CLEARSTRING_DELIMETER_START[] = "#$STRING_START$#";
const char PARSER_CLEARSTRING_DELIMETER_END[]   = "#$STRING_END$#";

const double HIT_TOLERANCE = 5.0;

/** Determines if x is included in the range x1 to x2 */
template<class X, class X1, class X2>
bool BETWEEN( const X& x, const X1& x1, const X2& x2 )
{
    return ( x >= x1 && x <= x2 )
           || ( x >= x2 && x <= x1 );
}

/** Determines if the argument is negative */
template<class X>
bool IS_NEGATIVE( const X& x ) { return std::fabs( x ) > 0.0001 ? ( x < 0.0 ) : 0; }

/** Determines if the argument is positive */
template<class X>
bool IS_POSITIVE( const X& x ) { return std::fabs( x ) > 0.0001 ? ( x > 0.0 ) : 0; }

/** Determines if the argument is small (< 1e-1) */
template<class X>
bool CloseToZero( const X x, const X threshold = X( 1e-1 ) )
{
    return std::fabs( x ) < threshold;
}

/** Determines if the argument is extremely small (< 10E-4) */
template<class X>
bool VeryCloseToZero( X x ) { return CloseToZero( x, X( 0.0001 ) ); }

/** Determines if the argument is very small (< 10E-3) */
template<class X>
bool IsNearZero( X x ) { return CloseToZero( x, X( 0.001 ) ); }

/** \deprecated Renamed to IsNearZero(). */
template<class X>
bool IS_ZERO( X x ) { return IsNearZero( x ); }

#ifndef MIN
/// Determines which argument is smaller
/// \deprecated Use disti::Min() instead.
#    define MIN( A, B ) ( ( A ) < ( B ) ? ( A ) : ( B ) )
#endif

#ifndef MAX
/// Determines which argument is larger
/// \deprecated Use disti::Min() instead.
#    define MAX( A, B ) ( ( A ) > ( B ) ? ( A ) : ( B ) )
#endif

/** Use for determining the current OpenGL version available in the current
  * runtime environment.
  * It may not be valid until called after a valid rendering context has been assigned.
  */
GLS_EXPORT float OpenGLVersion();

GLS_EXPORT bool gltIsExtSupported( const char* extension );

// Additional #defines
//From glext.h Available at http://oss.sgi.com/projects/ogl-sample/registry/ */
#ifndef GLES
#    define GLSTUDIO_CLAMP_TO_EDGE ( OpenGLVersion() >= 1.2f ? 0x812F : GL_CLAMP )
#else
#    define GLSTUDIO_CLAMP_TO_EDGE GL_CLAMP_TO_EDGE
#endif

/** GL Studio color defines */
// \enum color enumerations for use with GlsDefinedColor methods
enum GlsDefinedColorEnum
{
    GLS_COLOR_WHITE,
    GLS_COLOR_CYAN,
    GLS_COLOR_RED,
    GLS_COLOR_AMBER,
    GLS_COLOR_GREEN,
    GLS_COLOR_YELLOW,
    GLS_COLOR_MAGENTA,
    GLS_COLOR_BLACK,
    GLS_COLOR_BLUE,
    GLS_COLOR_MAX
};

/** Predefined colors (see \sa GlsDefinedColorEnum for the values). Use \sa GlsDefinedColor() for a range-checked version. */
GLS_EXPORT extern unsigned char glsDefinedColors[ GLS_COLOR_MAX ][ 4 ];

/** Gets a predefined color in \sa GlsDefinedColorEnum.
  * \param index of defined color
  * \return an unsigned char array of the specified index
  */
inline unsigned char* GlsDefinedColor( GlsDefinedColorEnum index )
{
    if( ( index < 0 ) || ( index >= GLS_COLOR_MAX ) )
        return glsDefinedColors[ 0 ];
    else
        return glsDefinedColors[ index ];
}
/** Allows the user to change the predefined colors */
inline void ChangeGlsDefinedColor(
    GlsDefinedColorEnum index,
    unsigned char       red,
    unsigned char       green,
    unsigned char       blue,
    unsigned char       alpha )
{
    if( ( index >= 0 ) && ( index < GLS_COLOR_MAX ) )
    {
        glsDefinedColors[ index ][ 0 ] = red;
        glsDefinedColors[ index ][ 1 ] = green;
        glsDefinedColors[ index ][ 2 ] = blue;
        glsDefinedColors[ index ][ 3 ] = alpha;
    }
}

#ifndef WIN32

/** helper class that enables use of basic_string< unsigned short > on unix
      * \see std::char_traits
      */
struct CharTraitsUnsignedShort
{
    typedef unsigned short char_type;
    typedef int            int_type;
    typedef std::streampos pos_type;
    typedef std::streamoff off_type;
    typedef std::mbstate_t state_type;

    static void assign( char_type& c1, const char_type& c2 )
    {
        c1 = c2;
    }

    static bool eq( const char_type& c1, const char_type& c2 )
    {
        return c1 == c2;
    }

    static bool lt( const char_type& c1, const char_type& c2 )
    {
        return c1 < c2;
    }

    static int compare( const char_type* s1, const char_type* s2, size_t n )
    {
        if( n == 0 )
        {
            return ( 0 );
        }
        do
        {
            if( *s1 != *s2++ )
            {
                return ( *s1 - *( s2 - 1 ) );
            }
            if( *s1++ == 0 )
            {
                break;
            }
        } while( --n != 0 );
        return ( 0 );
    }

    static size_t length( const char_type* s )
    {
        size_t x = 0u;
        while( *s++ )
        {
            ++x;
        }
        return ( x );
    }

    static const char_type* find( const char_type* s, size_t n, const char_type& a )
    {
        while( n-- > 0 )
        {
            if( *s == a )
            {
                return s;
            }
            s++;
        }
        return NULL;
    }

    static char_type* move( char_type* s1, const char_type* s2, size_t n )
    {
        return static_cast<char_type*>( memmove( s1, s2, n * sizeof( char_type ) ) );
    }

    static char_type* copy( char_type* s1, const char_type* s2, size_t n )
    {
        return static_cast<char_type*>( memcpy( s1, s2, n * sizeof( char_type ) ) );
    }

    static char_type* assign( char_type* s, size_t n, char_type a )
    {
        for( size_t idx = 0u; idx < n; ++idx )
        {
            s[ idx ] = a;
        }
        return ( s );
    }

    static char_type to_char_type( const int_type& c )
    {
        return static_cast<char_type>( c );
    }

    static int_type to_int_type( const char_type& c )
    {
        return static_cast<int_type>( c );
    }

    static bool eq_int_type( const int_type& c1, const int_type& c2 )
    {
        return c1 == c2;
    }

    static int_type eof()
    {
        return static_cast<int_type>( EOF );
    }

    static int_type not_eof( const int_type& c )
    {
        return ( c == eof() ) ? 0 : c;
    }
};

typedef std::basic_string<unsigned short, CharTraitsUnsignedShort> UTF16String;
typedef std::ofstream                                              UTF16Outfilestream;
typedef std::ostream                                               UTF16Outstream;
typedef std::string                                                UnicodeString;
typedef std::ofstream                                              UnicodeOutfilestream;
typedef std::ostream                                               UnicodeOutstream;

#else

typedef std::wstring   UTF16String;
typedef std::wofstream UTF16Outfilestream;
typedef std::wostream  UTF16Outstream;
typedef std::wstring   UnicodeString;
typedef std::wofstream UnicodeOutfilestream;
typedef std::wostream  UnicodeOutstream;

#endif

/** convert the given UTF8 string to UTF16
  * \param string in question
  * \return the given string in UTF16
  */
inline UTF16String
ConvertUTF8ToWide( const std::string& src )
{
    UTF16String ret;
    if( src.size() > 0u )
    {
        // allocate buffer for string plus terminator
        const unsigned int srcLen      = (unsigned int)src.size();
        const unsigned int utf16BufLen = (unsigned int)( src.size() + 1u );
        UTF16*             utf16Buf    = new UTF16[ src.size() + 1u ];
        // NULL out buffer
        memset( utf16Buf, 0, ( utf16BufLen * sizeof( UTF16 ) ) );

        // convert UTF8 to UTF16
        {
            const UTF8* srcUTF8     = (const UTF8*)( src.c_str() );
            UTF16*      targetUTF16 = utf16Buf;
            ConvertUTF8toUTF16( &srcUTF8, &srcUTF8[ srcLen ], &targetUTF16, &( targetUTF16[ utf16BufLen - 1u ] ), strictConversion );
        }
        // force terminate
        utf16Buf[ utf16BufLen - 1u ] = 0;
        // store out
#ifdef WIN32
        ret.assign( (wchar_t*)utf16Buf );
#else
        ret.assign( (unsigned short*)utf16Buf );
#endif

        // done with buf
        delete[]( utf16Buf );
        utf16Buf = NULL;
    }

    return ( ret );
}

//---------------------------------------------------------------------------
/**
  * Return whether two numbers are "equal" to eachother taking into account
  * a certain precision.  You can use this method on any numeric types and
  * even mix types as the parameters. Eg. you can compare integers with
  * floating point types or compare floats and doubles without casting.
  *
  * \param x  first number to use in the comparison which determines the range
  * \param y  number to check if within the range determined by x and precision
  * \param precision  number that is added to and subtracted from x to
  *                   determine the range to check y against.
  */
template<class T1, class T2>
bool Equal( T1 x, T2 y, float precision = 0.001f )
{
    return ( x - precision ) <= y && y <= ( x + precision );
}

//---------------------------------------------------------------------------
/**
  * Return the minimum of two objects. The class T must have the < operator
  * defined.
  */
template<class T>
const T& Min( const T& x, const T& y )
{
    return x < y ? x : y;
}

//---------------------------------------------------------------------------
/**
  * Return the maximum of two objects. The class T must have the < operator
  * defined.
  */
template<class T>
const T& Max( const T& x, const T& y )
{
    return x < y ? y : x;
}

//---------------------------------------------------------------------------
/**
  * Return the minimum of two objects determined by a predicate.
  * If pr(x, y) is true, x is returned else y.
  */
template<class T, class Pred>
const T& Min( const T& x, const T& y, Pred pr )
{
    return pr( x, y ) ? x : y;
}

//---------------------------------------------------------------------------
/**
  * Return the maximum of two objects determined by a predicate.
  * If pr(x, y) is true, y is returned else x.
  */
template<class T, class Pred>
const T& Max( const T& x, const T& y, Pred pr )
{
    return pr( x, y ) ? y : x;
}

/** \brief Class to contain current OpenGL view, projection and draw matrices */
class OpenGLMatrices
{
private:
    bool _needsDelete;

public:
    int*           viewMatrix;
    GlsMatrixType* projMatrix;
    GlsMatrixType* modelMatrix;

    /** Default constructor
      * Keeps everything NULL */
    GLS_EXPORT OpenGLMatrices();

    /** Copy constructor
      * Pointers are copied as-is, copies of the
      * data are NOT made. */
    GLS_EXPORT OpenGLMatrices( const OpenGLMatrices& src );

    /** Another constructor.
      * Pointers are copied as-is, copies of the
      * data are NOT made. */
    GLS_EXPORT OpenGLMatrices( int* view,
        GlsMatrixType*              proj,
        GlsMatrixType*              model );

    /** Destructor */
    GLS_EXPORT ~OpenGLMatrices();

    /** Retrieves the current OpenGL Matrices from the
      * OpenGL Subsystem */
    GLS_EXPORT void GetCurrent();
};

/** Find a transformation that will convert to a new coordinate
  * system defined by the given origin and basis vectors (i,j,k).
  * \note The new i,j,k vectors are in respect to the current origin.
  *       (i.e. for transformation that moves the origin
  *      along the x axis by 5 units you should pass in
  *      (Vector(5,0,0), Vector(1,0,0), Vector(0,1,0) , Vector(0,0,1))
  *       NOT (Vector(5,0,0), Vector(6,0,0), Vector(5,1,0) , Vector(5,0,1))
  * Template argument is either double or float.
  * \param new_origin Vector to the new coordinate system origin.
  * \param new_i Vector parallel to the new x-axis with magnitude equal to one unit in the new coordinate system.
  * \param new_j Vector parallel to the new y-axis with magnitude equal to one unit in the new coordinate system.
  * \param new_k Vector parallel to the new z-axis with magnitude equal to one unit in the new coordinate system.
  *
  * \returns transformation matrix to the new coordinate system
  */
template<class T>
GlsMatrixAffine<T> FindCoordinateTransformation( const Vector& new_origin, const Vector& new_i, const Vector& new_j, const Vector& new_k )
{
    GlsMatrixAffine<T> transform;
    GlsMatrixAffine<T> rotation_scaling;

    // First translate to the new origin

    transform.Translate( -new_origin );

    // Build a matrix taking the standard basis vectors to the new basis vectors

    rotation_scaling( 0, 0 ) = new_i.x;
    rotation_scaling( 0, 1 ) = new_j.x;
    rotation_scaling( 0, 2 ) = new_k.x;
    rotation_scaling( 1, 0 ) = new_i.y;
    rotation_scaling( 1, 1 ) = new_j.y;
    rotation_scaling( 1, 2 ) = new_k.y;
    rotation_scaling( 2, 0 ) = new_i.z;
    rotation_scaling( 2, 1 ) = new_j.z;
    rotation_scaling( 2, 2 ) = new_k.z;

    // Invert because we want the new basis vectors to become the standard basis vectors
    rotation_scaling.Invert();

    // Combine the translation and rotation to produce the complete transformation
    return rotation_scaling * transform;
}

template<class T>
void FindCoordinateTransformation( const Vector& new_origin, const Vector& new_i, const Vector& new_j, const Vector& new_k, GlsMatrixAffine<T>& result )
{
    GlsMatrixAffine<T> transform;
    GlsMatrixAffine<T> rotation_scaling;

    // First translate to the new origin

    transform.Translate( -new_origin );

    // Build a matrix taking the standard basis vectors to the new basis vectors

    rotation_scaling( 0, 0 ) = new_i.x;
    rotation_scaling( 0, 1 ) = new_j.x;
    rotation_scaling( 0, 2 ) = new_k.x;
    rotation_scaling( 1, 0 ) = new_i.y;
    rotation_scaling( 1, 1 ) = new_j.y;
    rotation_scaling( 1, 2 ) = new_k.y;
    rotation_scaling( 2, 0 ) = new_i.z;
    rotation_scaling( 2, 1 ) = new_j.z;
    rotation_scaling( 2, 2 ) = new_k.z;

    // Invert because we want the new basis vectors to become the standard basis vectors
    rotation_scaling.Invert();

    // Combine the translation and rotation to produce the complete transformation
    result = rotation_scaling * transform;
}

/** Gets the transformation from one DisplayObject's object coordinates to another's
  * Note: This method uses a screen-space transformation (DisplayObject::ModelMatrix).  This requires that the two objects have been PreDrawn with the same view, but they do not need to be part of the same object heirarchy.
  * Use GetObjectCoordinatesTransform unless GetObjectCoordinatesTransformSameView is required.
  *
  * \sa GetObjectCoordinatesTransform
  *
  * \param from The DisplayObject to start at
  * \param to The DisplayObject to end at
  * \param outTransform Out parameter - If the function returns true, this will contain the resulting transformation.
  * \returns true on success, false if there was an error
  */
GLS_EXPORT bool GetObjectCoordinatesTransformSameView( DisplayObject* from, DisplayObject* to, GlsMatrixType* outTransform );

/** Gets the Topmost Display Frame
  *
  * \param from The DisplayFrame to start at
  * \returns the Topmost Display Frame
  */
GLS_EXPORT DisplayFrame* GetTopLevelDisplayFrame( DisplayFrame* frame );

/** Gets the transformation from one DisplayObject's object coordinates to another's (if possible)
  * This is the preferred method for determining the coordinate space relationship between two objects that have DynamicTransforms applied.
  * Note: This method requires that the two objects are part of the same object heirarchy.
  * Consider using GetObjectCoordinatesTransformSameView if your situation does not meet this requirement.
  *
  * \code
  * // Example: Move objB to be in the same location as objA (including all DynamicTransforms)
  * // Change Location of objB so that it's RotationPoint aligns with the RotationPoint of objA
  * GlsMatrixType transform;
  * if( GetObjectCoordinatesTransform( objA, objB, &transform ) )
  * {
  *     Vector objA_rotationPoint_transformed = transform * (objA->Location() + objA->RotationPoint());
  *     objB->Location( objA_rotationPoint_transformed - objB->RotationPoint() );
  * }
  * else
  * {
  *     // Error: objects are not in the same heirarchy
  * }
  * \endcode
  *
  * \sa GetObjectCoordinatesTransform
  *
  * \param from The DisplayObject to start at
  * \param to The DisplayObject to end at
  * \param outTransform Out parameter - If the function returns true, this will contain the resulting transformation.
  * \returns true on success, false if the objects are not in the same heirarchy.
  */
GLS_EXPORT bool GetObjectCoordinatesTransform( DisplayObject* from, DisplayObject* to, GlsMatrixType* outTransform );

/** Test if the given points are not colinear (they are not in a line)
  * \return true if the points are not colinear
  * \return false if the points are colinear
  */
GLS_EXPORT bool NotColinear( const Vector& a, const Vector& b, const Vector& c );

/** Search the given Vertex array for the first three non-colinear vertices.
  * \param arraySize The size of vertex_array
  * \param array The Vertex array
  * \param index1 variable to receive 1st array index
  * \param index2 variable to receive 2nd array index
  * \param index3 variable to receive 3rd array index
  * \param isVectorArray true if array points to a Vector array, false if it
  *                      points to a Vertex array
  *
  * \return true If the vertices were found
  * \returns false  If there are not three non-colinear vertices in the array
  *                 if this occurs, the index values are undefined
  */
GLS_EXPORT bool FindNonColinearVertices( int arraySize, Vector array[],
    int& index1, int& index2, int& index3,
    bool isVectorArray = true );

/** Vertex version of FindNonColinearVertices */
inline bool FindNonColinearVertices( int arraySize, Vertex array[], int& index1, int& index2, int& index3 )
{
    return FindNonColinearVertices( arraySize, array, index1, index2, index3, false );
}

/** Recalculate the texture points of a given DisplayObject
  * based on its valid texture coordinates
  *
  * \return true On success
  * \return false If the texture points could not be calculated.
  *               (The object doesn't have three non-colinear vertices or doesn't have texture coordinates.)
  */
GLS_EXPORT bool CalculateTexPointsFromTexCoords( DisplayObject* object );

/** Encodes a string such that if it contains newlines, it will be wrapped with the "#$STRING_START$#" and "#$STRING_END$#" delimiters.
  * \param dest Destination string
  * \param src Source string
  * \param dest_str_length Size of the destination buffer
  * \return The length of the encoded string.
  */
GLS_EXPORT int EncodeString( char* dest, const char* src, const int dest_str_length );

/** Encodes a std::string such that there are no whitespace characters in the string
  * \param src Source string
  * \return The encoded string
  */
GLS_EXPORT std::string EncodeString( const std::string& src );

/** Returns a minimum length for a call to EncodeString.
  * This is based on the clear text delimeters
  */
GLS_EXPORT int EncodedStringMinLength();

/** Encodes a string using C language encoding
  * \param dest Destination string
  * \param src Source string
  * \param dest_str_length Size of the destination buffer
  * \return The length of the encoded string
  */
GLS_EXPORT int C_EncodeString( char* dest, const char* src, const int dest_str_length );

/** Returns and encoded std::string using C language encoding
  * \param src Source string
  * \return The encoded string
  */
GLS_EXPORT std::string C_EncodeString( const std::string& src );

/** Decodes a string that was encoded using EncodeString
  * \param dest Destination string
  * \param src Source string
  * \param dest_str_length Size of the destination buffer
  * \return The length of the encoded string
  */
GLS_EXPORT int DecodeString( char* dest, const char* src, const int dest_str_length );

/** Decodes a std::string that was encoded using EncodeString
  * \param src Encoded Source string
  * \return The decoded string
  */
GLS_EXPORT std::string DecodeString( const std::string& src );

/** The InlinePixmap structure  */
typedef struct
{
    int            width;
    int            height;
    int            comprSize;
    unsigned char* pixels;
} InlinePixmap;

GLS_EXPORT char* MakeRelativePath( const char* originalPath, const char* relativePath );
GLS_EXPORT void  ConvertBackslashToSlash( char* str );
GLS_EXPORT void  ConvertBackslashToSlash( std::string& str );

/** Determines if the given value falls in any of the ranges passed in.
  *  range_check(int number_of_ranges, double test_value,
  *              int index_0,double range_0_min,double range_0_max,
  *
  *              ...
  *
  *              int index_n,double range_n_min,double range_n_max);
  *
  *  For example, to return 1 for values 0-10 and 2 for values 10-20:
  *
  *  index = range_check(2,val,
  *                      1, 0.0,  10.0,
  *                      2, 10.0, 20.0);
  */

GLS_EXPORT int range_check( int num, double val, ... );

/** Attempts to open the given file.  Pops up an error message box if the
  * attempt fails
  * \param filename The name of the file to open
  * \param flags fopen style file arguments (e.g. "r")
  * \param f Contains file pointer on success
  * \return True if the operation was successful
  */
GLS_EXPORT int Safe_fopen( const char* filename, char* flags, FILE** f );
/** Stream version */
GLS_EXPORT int Safe_fopen( const char* filename, char* flags, std::fstream& outstr );

#ifdef ANDROID
/** Sets if assets should be loaded directly from the apk (default true).
  * This only affects Android builds.
  * \param enableDirectAssetLoading true to allow assets to be loaded directly from the apk
  *                                 false to force assets to be read from the resource directory (\see SetResourcePath)
  * \post HasAssetExtension returns false for all filetypes if direct asset loading was disabled
  */
GLS_EXPORT void EnableDirectAssetLoading( bool enableDirectAssetLoading );

/** Returns if the filetype is one that can be loaded directly from the apk assets.
  * This only affects Android builds.
  * \param filename The filename with extension to check
  * \return True if the filetype can be loaded directly from the apk assets,
  *         False if the file is loaded from internal or external storage
  */
GLS_EXPORT bool HasAssetExtension( const char* filename );

/** Returns if the file exists in the apk assets.
   * This only affects Android builds.
   * \param filename The name of the file
   * \return True if the file is an asset that can be opened.
   *         Returns false if no asset exists with filename or the pointer to the AAssetManager, set with SetAssetManager, is null.
   */
GLS_EXPORT bool AssetExists( const char* filename );

/** Sets the Android Asset Manager to use.
  * When the assetManager is null, apk assets cannot be loaded.
  * This only affects Android builds.
  * \param assetManager The pointer to the AAssetManager
  */
GLS_EXPORT void SetAssetManager( AAssetManager* assetManager );
#endif

#if defined( ANDROID ) || ( defined( __APPLE__ ) && defined( GLES ) ) || ( defined( LINUX ) && defined( GLES ) ) || defined( QNX ) || defined( INTEGRITY )
/** Prepends the resource path to a file name.
  * \param[in] filename_ The name of the file
  * \return string containing ResourcePath+filename_, with OS specific path.
  *         On Android, apk asset files are not prepended with a path.
  */
GLS_EXPORT std::string ResolvePath( const char* filename_ );

/** Sets the path for locating resource files.
  * On Android, this is the location where resources outside of apk assets are found.
  * \param resourcePath The path where application resources will be found
  */
GLS_EXPORT void SetResourcePath( const char* resourcePath );

/** Attempts to open the given file. Prepends the filename with the path from SetResourcePath
  * for non-absolute paths.
  * On Android, filenames that match an apk asset are opened. Opened assets should be closed
  * with fclose to free resources, not with the Android Asset Manager close function (AAsset_close)
  * \param filename The name of the file to open
  * \param flags fopen style file arguments (e.g. "r")
  * \pre On Android, Asset Manager != NULL, set with SetAssetManager, when opening an apk asset
  * \return FILE pointer or NULL otherwise
  */
GLS_EXPORT FILE* gls_fopen( const char* filename, const char* flags );
#else
/** Pushes a resource search path onto the stack.  The CWD is always
  * implicitly searched first.  The resource search paths are local to
  * the calling thread only.  This function should be called from the same
  * thread as the resources are loaded from.
  * \param resourcePath The directory path to add to the search paths
  */
GLS_EXPORT void PushResourcePath( const char* resourcePath );

/** Remove the first search path from the stack.  The resource search paths
  * are local to the calling thread only.  This function should be called from
  * the same thread as the matching PushResourcePath.
  */
GLS_EXPORT void PopResourcePath();

/** Pushes a function that can locate resources.  The Resources finders are applied after the resource paths are searched
  * \param finder The function that can locate resources to add to the search paths
  */
GLS_EXPORT void PushResourceFinder( std::string ( *finder )( const std::string& ) );

/** Resolves the given path searching the resource path list.  The
  * CWD is always implicity searched first.
  * \param path The relative path to resolve
  */
GLS_EXPORT std::string ResolvePath( const char* path );

// helper method taking a std::string
inline std::string ResolvePath( const std::string& path )
{
    return ResolvePath( path.c_str() );
}

/** Attempts to open the given file.  Relative file paths
  * are resolved using ResolvePath.
  * \param filename The name of the file to open
  * \param flags fopen style file arguments (e.g. "r")
  * \return FILE pointer or NULL otherwise
  */
GLS_EXPORT FILE* gls_fopen( const char* filename, const char* flags );
#endif

/** Attempts to unlink (delete) a file given
    a UTF-8 encoded filename.
 This function is especially useful on Windows platforms where the
 standard function expects UTF-16 encoded wide character filenames.
  \param     filename The filename to unlink
  \return    Returns 0 is successful, otherwise returns -1 and sets errno.
*/
int gls_unlink( const char* filename );

#if defined( __APPLE__ ) && defined( GLES )
/** \return a string indicating the location of a specific file in the default resource bundle.
  * This method is designed for runtime platforms that have a pre-defined bundle
  * location that is not immediately known to the application until runtime.
  * in iOS, this returns the path to the main application bundle with the file name appended.
  * \param fileName A string referring to the file without a path.
  */
GLS_EXPORT std::string GetAbsolutePathAndFileNameInDefaultResourceBundle( const char* fileName );
#endif

/** Prepends the resource path to a file name.
  * \param[in] fileName The name of the file
  * \return string containing ResourcePath + fileName, with OS specific path.
  *         On Android, apk asset files are not prepended with a path.
  */
GLS_EXPORT std::string ResolveRuntimeResourcePath( const char* fileName );

/** \return true if the file exists, false otherwise
  * \param filename The filename to check
  */
GLS_EXPORT bool FileExists( const char* filename );
GLS_EXPORT bool FileExists( const std::string& filename );

/** \return true if the file exists and is a directory, false otherwise
  * \param filename The filename to check
  */
GLS_EXPORT bool IsDirectory( const char* filename );
GLS_EXPORT bool IsDirectory( const std::string& filename );

/** \return The file extension for a filepath
  * \param filepath Filepath to get extension from
  */
GLS_EXPORT std::string FileExtension( const std::string& filepath );

/** \return The filename from a file path by stripping off anything to the left of a slash
  * \param filepath
  */
GLS_EXPORT std::string FileName( const std::string& filepath );

/** \return  a string containing the path portion of a filename
  * by stripping off everything to the right of the rightmost slash
  * \param filepath A string containing a file with a path
  */
GLS_EXPORT std::string FilePath( const std::string& filepath );

/** \return  a pointer to the string containing the path portion of a filename
  * by stripping off everything to the right of the rightmost slash
  * \param name A string containing a file with a path
  * \warning If this function is called more than once all previous values WILL CHANGE to contain the newest value
  * \deprecated Use FilePath instead
  */
GLS_EXPORT const char* GetFilePath( const char* name );

/** \return The filename from a file path by stripping off anything to the left of a slash
  * \param name A string containing just the file name without a path
  * \warning If this function is called more than once all previous values WILL CHANGE to contain the newest value
  * \deprecated Use FileName instead
  */
GLS_EXPORT char* GetFileName( const char* name );

/** Appends a trailing slash to a path string, if one isn't there already
  * \param s File path
  */
GLS_EXPORT void AppendTrailingSlash( char* s );

/** Appends a trailing slash to a path string, if one isn't there already
  * \param s File path
  */
GLS_EXPORT void AppendTrailingSlash( std::string& s );

/** Convert a directory path to have the correct OS
  * slashes /, or \.  Also make sure that the path ends in a \, or /.
  * So you always have the form <name 1>\\<name 2>...<name n>\\\, or <name 1>/<name 2>...<name n>/
  * \param path A path to convert
  * \return a "new-ed" string which may be longer than the original.
  * It is the calling functions responsibility to free the memory.
  */
GLS_EXPORT char* PathToOS( const char* path );

/** \return The file extension for a filename
  * \param filename Filename to get extension from
  * No longer allocates memory, you can let the returned string
  * be colected as it falls out of scope
  */
GLS_EXPORT std::string GetExtension( const std::string& filename );

/** Gets the file name from a filename with path
  * It does not allocate new memory, but rather just returns
  * a pointer inside the original string
  */
GLS_EXPORT const char* GetBaseName( const char* path );

/** \return Pointer to a position within the given \a path where the filename starts.
  * \deprecated This function is not const-correct. Prefer the const-correct version.
  * \sa GetBaseName( const char* )
  */
GLS_EXPORT char* GetBaseName( char* path );

/** Removes and double slashes from a path.
  * It will look for the specified type of slash.
  * It will modify path, but since it can only shrink,
  * no allocation is done.
  * \param path The path to operate on.
  * \param slash The type of slash to search for.
  */
GLS_EXPORT void RemoveDoubleSlashes( char* path, char slash = '/' );

/** Remove all space ' ' characters from the incoming string.
  * \param entry    String to be manupulated.
  */
GLS_EXPORT void RemoveSpaces( std::string& entry );

/** Remove all space ' ' characters from the beginning and end of the string.
  * \param entry    String to be manupulated.
  */
GLS_EXPORT void TrimSpaces( std::string& entry );

/** \return The minimum angular distance between angle1 and angle2 in degrees
  * \param angle1 First angle
  * \param angle2 Second angle
  */
GLS_EXPORT float AngularDistanceDeg( float angle1, float angle2 );

/** \return The minimum angular distance between angle1 and angle2 in radians
  * \param angle1 First angle
  * \param angle2 Second angle
  */
GLS_EXPORT float AngularDistanceRad( float angle1, float angle2 );

GLS_EXPORT bool ContainsNonBlank( const std::string& val );

GLS_EXPORT bool GetNoSpaces( FILE* f, char* result, int maxLen );
GLS_EXPORT bool GetToEnd( std::istream& instr, std::string& result, bool decode );
GLS_EXPORT bool GetVertex( std::istream& instr, Vertex* vert, bool getColor );

/** Searches the specified binary file for the specified tag, and adds what immediatly follows the tag to the nameList.
  * Returns true if at least one is found, false otherwise.
  */
GLS_EXPORT bool GetComponentClassNames( const char* dllFileName, DynamicArray<std::string>& nameList, const char* createClassTag = "CreateComponent_" );

/** Opens the DLL and attempts to run GlsDefaultClassName(), if found.
  * Returns an empty string if not found. */
GLS_EXPORT std::string GetDefaultComponentClassName( const char* dllFileName );

/** Returns the qualified instance name of an object that is
  * contained within given DisplayFrame. (e.g "cockpit.altimeter.needle")
  * Note that names are only added for each DisplayFrame (not every Group)
  * and the name of the topFrame is not included in the qualified name.
  * \param topFrame The frame in which the qualification will make sense.
  * \param obj The object which is a direct child or located somewhere below topFrame.
  * \returns The qualified instance name or an empty string if the qualified
  *          instance name could not be determined. */
GLS_EXPORT std::string GetQualifiedInstanceName( const DisplayFrame* topFrame, const DisplayObject* obj );

#if !defined( GLES ) || defined( GLES_ANGLE )
GLS_EXPORT bool OpenFileDialog( Fl_Window* win, char* filePath, unsigned int filePathSize,
    char* directory = NULL, const char* filterStr = NULL,
    const char* defaultExt = NULL, const char* title = NULL,
    bool multiSelect = false, bool createFile = false,
    bool fileMustExist = false, bool pathMustExist = false,
    bool noChangeDirectory = false );

GLS_EXPORT bool SaveFileDialog( Fl_Window* win, char* filePath, unsigned int filePathSize,
    char* directory = NULL, const char* filterStr = NULL,
    const char* defaultExt = NULL, const char* title = NULL,
    bool createFile    = false,
    bool fileMustExist = false, bool pathMustExist = false,
    bool noChangeDirectory = false );
#endif
GLS_EXPORT void CheckGLError( void );

//---------------------------------------------------------------------------
/**
  * Returns a string which is the uppercase version of the passed parameter.
  *
  * \param str   original string to convert to Uppercase
  *
  * \return a string copy of the original but in all caps.
  */
GLS_EXPORT std::string Uppercase( const std::string& str );

GLS_EXPORT std::string ReplaceEnvironmentVariables( const char* originalPath );

/** A singleton used for accessing the command line arguments in generated code  */
class glsCommandLine
{
public:
    GLS_EXPORT      glsCommandLine();
    GLS_EXPORT void ReadCommandLine( int argc, char** argv );
    GLS_EXPORT void Usage();

    int    _argc;
    char** _argv;

    /** Whether or not the app should run in silent mode */
    bool SilentMode() const { return _silentMode; }

    static GLS_EXPORT glsCommandLine* Instance();

private:
    bool                             _silentMode;
    static ScopedPtr<glsCommandLine> _instance;
};

/** Used to make interface information visible to the user at design time*/
class InterfaceDescriptionClass DISTI_FINAL
{
    char* _code;    // e.g. "DynamicRotate("
    char* _usage;   // e.g. "void DynamicRotate(float angle, int axis)"
    char* _comment; // e.g. "Sets dynamic rotation in degrees for the specified axis"

public:
    GLS_EXPORT InterfaceDescriptionClass();
    GLS_EXPORT InterfaceDescriptionClass( const char* code, const char* usage, const char* comment );

    GLS_EXPORT ~InterfaceDescriptionClass();
    GLS_EXPORT InterfaceDescriptionClass( const InterfaceDescriptionClass& source );
    GLS_EXPORT InterfaceDescriptionClass& operator=( const InterfaceDescriptionClass& source );

    GLS_EXPORT void Code( const char* );
    GLS_EXPORT void Usage( const char* );
    GLS_EXPORT void Comment( const char* );

    const char* Code() const { return _code; }
    const char* Usage() const { return _usage; }
    const char* Comment() const { return _comment; }

#if defined( DISTI_HAS_RVAL_REFS )
    InterfaceDescriptionClass( InterfaceDescriptionClass&& source )
        : _code( NULL )
        , _usage( NULL )
        , _comment( NULL )
    {
        StealFrom( source );
    }

    InterfaceDescriptionClass& operator=( InterfaceDescriptionClass&& source )
    {
        if( this != &source )
        {
            // Destroy current values
            delete[] _code;
            delete[] _usage;
            delete[] _comment;

            StealFrom( source );
        }
        return *this;
    }

private:
    void StealFrom( InterfaceDescriptionClass& source )
    {
        // Take ownership
        _code    = source._code;
        _usage   = source._usage;
        _comment = source._comment;

        // Relieve of ownership
        source._code    = NULL;
        source._usage   = NULL;
        source._comment = NULL;
    }
#endif
};

typedef DynamicArray<InterfaceDescriptionClass> InterfaceListType;

/** Base class for GlsMultiVal template */
class GlsMultiValBase
{
public:
    virtual ~GlsMultiValBase() {}

    //These are used to avoid template problems with VC6.0
    typedef std::ostream ostreamType;
    typedef std::istream istreamType;

    virtual void StreamOut( ostreamType& outstr ) const = 0;
    virtual void StreamIn( istreamType& instr )         = 0;
};

/** GlsMultiVal is used to effectivly create a structure containing up
  * to 10 values of varying types.  An instance of the class is capable
  * of streaming itself to and from a text stream.  The individual values
  * will be separated by spaces when written and read from the stream.
  * The types have to follow some rules:
  *  - They must themselves have the << and >> stream operators defined.
  *  - operator>> must read all data written by operator<< and must not consume spaces or other characters that follow it
  *  - They must have a default constructor
  *  - They must have a copy constructor
  *  - They shall not be void* (it is used for determining the end of the desired types).
  *  - If a GlsPropString is used, there must be only one, and it *must* be the
  *    last entry in the GlsMultiVal instance.
  *  - A GlsPropStringQuoted will work in any position.
  * This is intended primarily for the GL Studio end user to use as a Class Property type.
  */
template<class T1,
    class T2  = void*,
    class T3  = void*,
    class T4  = void*,
    class T5  = void*,
    class T6  = void*,
    class T7  = void*,
    class T8  = void*,
    class T9  = void*,
    class T10 = void*>
class GlsMultiVal : public GlsMultiValBase
{
    int  _numVals;
    void CalcNumVals()
    {
        _numVals = 1;
        if( typeid( T2 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T3 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T4 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T5 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T6 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T7 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T8 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T9 ) != typeid( void* ) )
            _numVals++;
        else
            return;
        if( typeid( T10 ) != typeid( void* ) )
            _numVals++;
        else
            return;
    }

public:
    T1  _val1;
    T2  _val2;
    T3  _val3;
    T4  _val4;
    T5  _val5;
    T6  _val6;
    T7  _val7;
    T8  _val8;
    T9  _val9;
    T10 _val10;

    /** Default constructor.
      * The _val member types must have default constructors.
      */
    GlsMultiVal()
    {
        CalcNumVals();
    }

    /** Copy constructor.
      * This GlsMultiVal will copy values from the src GlsMultiVal.
      * \param src  GlsMultiVal object to use for initialization.
      * \return
      */
    GlsMultiVal( const GlsMultiVal& src )
        : _val1( src._val1 )
        , _val2( src._val2 )
        , _val3( src._val3 )
        , _val4( src._val4 )
        , _val5( src._val5 )
        , _val6( src._val6 )
        , _val7( src._val7 )
        , _val8( src._val8 )
        , _val9( src._val9 )
        , _val10( src._val10 )
    {
        CalcNumVals();
    }
    /** Full constructor.  Creates a GlsMultiVal object with the provided data.
      * \param val1  First value to use for intialization of type T1.
      * \param val2  First value to use for intialization of type T2.
      * \param val3  First value to use for intialization of type T3.
      * \param val4  First value to use for intialization of type T4.
      * \param val5  First value to use for intialization of type T5.
      * \param val6  First value to use for intialization of type T6.
      * \param val7  First value to use for intialization of type T7.
      * \param val8  First value to use for intialization of type T8.
      * \param val9  First value to use for intialization of type T9.
      * \param val10  First value to use for intialization of type T10.
      * \return
      */
    GlsMultiVal(
        const T1&  val1,
        const T2&  val2  = T2(),
        const T3&  val3  = T3(),
        const T4&  val4  = T4(),
        const T5&  val5  = T5(),
        const T6&  val6  = T6(),
        const T7&  val7  = T7(),
        const T8&  val8  = T8(),
        const T9&  val9  = T9(),
        const T10& val10 = T10() )
        : _val1( val1 )
        , _val2( val2 )
        , _val3( val3 )
        , _val4( val4 )
        , _val5( val5 )
        , _val6( val6 )
        , _val7( val7 )
        , _val8( val8 )
        , _val9( val9 )
        , _val10( val10 )
    {
        CalcNumVals();
    }

    /** Compares two multival objects for equality */
    virtual bool operator==( const GlsMultiVal& val ) const
    {
        bool rval = true;
        // Only compare the number of used values.
        switch( _numVals )
        {
            // No breaks is intentional
        case 10: rval &= ( _val10 == val._val10 );
        case 9: rval &= ( _val9 == val._val9 );
        case 8: rval &= ( _val8 == val._val8 );
        case 7: rval &= ( _val7 == val._val7 );
        case 6: rval &= ( _val6 == val._val6 );
        case 5: rval &= ( _val5 == val._val5 );
        case 4: rval &= ( _val4 == val._val4 );
        case 3: rval &= ( _val3 == val._val3 );
        case 2: rval &= ( _val2 == val._val2 );
        case 1:
            rval &= ( _val1 == val._val1 );
            break;
        default:
            rval = false;
        }
        return rval;
    }

    /** Inverse of equality */
    virtual bool operator!=( const GlsMultiVal& val ) const
    {
        return !( *this == val );
    }

    /** StreamOut().  This function serializes itself into the provided stream object.
      * \param outstr  This is the object used by the GlsMultiVal class to serialize itself onto.
      * \return
      */
    virtual void StreamOut( ostreamType& outstr ) const
    {
        outstr << _val1;
        if( _numVals >= 2 )
            outstr << " " << _val2;
        if( _numVals >= 3 )
            outstr << " " << _val3;
        if( _numVals >= 4 )
            outstr << " " << _val4;
        if( _numVals >= 5 )
            outstr << " " << _val5;
        if( _numVals >= 6 )
            outstr << " " << _val6;
        if( _numVals >= 7 )
            outstr << " " << _val7;
        if( _numVals >= 8 )
            outstr << " " << _val8;
        if( _numVals >= 9 )
            outstr << " " << _val9;
        if( _numVals >= 10 )
            outstr << " " << _val10;
    }

    /** StreamIn().  Uses the provided istream object to populate the current GlsMultiVal object
      * \param instr  This is the stream object used by the GlsMultiVal instance to populate itself.
      * \return
      */
    virtual void StreamIn( istreamType& instr )
    {
        instr >> _val1;
        if( _numVals >= 2 )
        {
            instr.get(); // The separating space
            instr >> _val2;
        }
        if( _numVals >= 3 )
        {
            instr.get();
            instr >> _val3;
        }
        if( _numVals >= 4 )
        {
            instr.get();
            instr >> _val4;
        }
        if( _numVals >= 5 )
        {
            instr.get();
            instr >> _val5;
        }
        if( _numVals >= 6 )
        {
            instr.get();
            instr >> _val6;
        }
        if( _numVals >= 7 )
        {
            instr.get();
            instr >> _val7;
        }
        if( _numVals >= 8 )
        {
            instr.get();
            instr >> _val8;
        }
        if( _numVals >= 9 )
        {
            instr.get();
            instr >> _val9;
        }
        if( _numVals >= 10 )
        {
            instr.get();
            instr >> _val10;
        }
    }
};

GLS_EXPORT std::ostream& operator<<( std::ostream& outstr, const GlsMultiValBase& multiVal );
GLS_EXPORT std::istream& operator>>( std::istream& instr, GlsMultiValBase& multiVal );

/** GlsPropString is designed to be used as a string in GL Studio Class Properties.
  * It writes itself out as a single line, and will read in up to the next newline.
  * It will attempt to convert itself to and from std::strings.
  * If it is used in a GlsMultiVal, there must be only one, and it *must* be the
  * last entry in the GlsMultiVal instance.
  * See GlsPropStringQuoted for more usefulness in GlsMultiVal.
  */
class GlsPropString
{
public:
    std::string _string;

    /** Default constructor  Creates an empty GlsPropString. */
    GlsPropString()
        : _string( "" )
    {
    }
    /** Create a new GlsPropString using the provided std string.
      * \param str  std::string to use to create the GlsPropString
      * \return
      */
    GlsPropString( const std::string& str )
        : _string( str )
    {
    }

    /** Create a  new GlsPropString using the provided c-style string.
      * \param str  c-style string to use to create the GlsPropString.
      * \return
      */
    GlsPropString( const char* str )
        : _string( str ? str : "" )
    {
    }

    operator std::string() const
    {
        return _string;
    }

    /** Get the string value for this object.
      * \return std::string containing the string value for this object.
      */
    std::string& String()
    {
        return _string;
    }

    /** Checks lexicographic equality of the two arguments */
    friend inline bool operator==( const GlsPropString& str1, const GlsPropString& str2 )
    {
        return str1._string == str2._string;
    }

    /** Checks lexicographic inequality of the two arguments */
    friend inline bool operator!=( const GlsPropString& str1, const GlsPropString& str2 )
    {
        return !( str1 == str2 );
    }
};

inline std::ostream& operator<<( std::ostream& outstr, const GlsPropString& str )
{
    outstr << disti::C_EncodeString( str._string );
    return outstr;
}
inline std::istream& operator>>( std::istream& instr, GlsPropString& str )
{
    std::string temp;
    disti::GetToEnd( instr, temp, false );
    str._string = disti::DecodeString( temp );

    return instr;
}
/** GlsPropStringQuoted is designed to be used as a string in GL Studio Class Properties.
  * It writes itself out as a single line surrounded with quotes (""), and will read in up to the next un-escaped quote.
  * It will attempt to convert itself to and from std::strings.
  * Use of GlsPropStringQuoted is preferred over GlsPropString for use in a GlsMultiVal.
  */
class GlsPropStringQuoted
{
public:
    std::string _string;

    /** Default constructor, create an empty GlsPropStringQuoted object. */
    GlsPropStringQuoted()
    {
    }
    /** Constructor, create a new GlsPropStringQuoted object using the provided std::string object
      * \param str  std::string object to use to create the GlsPropStringQuoted object
      * \return
      */
    GlsPropStringQuoted( const std::string& str )
        : _string( str )
    {
    }
    /** Constructor, create a new GlsPropStringQuoted object using the provided c-style string
      * \param str  c-style string to use to create the GlsPropStringQuoted object
      * \return
      */
    GlsPropStringQuoted( const char* str )
        : _string( str )
    {
    }

    operator std::string() const
    {
        return _string;
    }

    std::string& String()
    {
        return _string;
    }

    bool operator==( const GlsPropStringQuoted& str ) const
    {
        return str._string == _string;
    }
};

inline std::ostream& operator<<( std::ostream& outstr, const GlsPropStringQuoted& str )
{
    outstr << '\"' << disti::C_EncodeString( str._string ) << '\"';
    return outstr;
}

inline std::istream& operator>>( std::istream& instr, GlsPropStringQuoted& str )
{
    std::string temp;
    str._string = "";

    // The next character should be a quote.
    // If it is not, we will attempt to do something useful anyway.
    if( instr.peek() != '\"' )
    {
        disti::GetToEnd( instr, temp, false );
    }
    else // Starts with quote
    {
        // Go ahead and consume the quote
        instr.get();

        int lastChar = 0;
        int currChar = 0;
        // Loop until we find an un-escaped quote or we run out of stream.
        while( instr.good() )
        {
            lastChar = currChar;
            currChar = instr.get();
            if( currChar != -1 )
            {
                if( currChar == '\"' && lastChar != '\\' )
                    break; // We found the trailing quote
                temp += (char)currChar;
            }
        }
    }

    str._string = disti::DecodeString( temp );

    return instr;
}

#ifndef WIN32
void SpawnBrowser( const char* url );
#endif

/** Call this to check for the availability of a DiSTI conrolled license.
  * It does not hold the license.  It only checks it out and checks it back in.
  * \param licenseGroupName A name for what this license allows.  i.e. "GL Studio Runtime".
  * \param feature The specific feature that will be checked out.
  * \param version The specific version that will be checked out.
  * \param quiet When true, no popup will occur upon missing license.
  */
GLS_EXPORT bool CheckDistiLicense( const char* licenseGroupName, const char* feature, const char* version, bool quiet );

/** This will set the m parameter to an orthographic projection.
  * The current value of m is ignored.
  * This does NOT make any OpenGL calls.
  */
GLS_EXPORT void GlsGetOrtho( GlsMatrixType& m,
    double                                  left,
    double                                  right,
    double                                  bottom,
    double                                  top,
    double                                  zNear,
    double                                  zFar );

/** This will set the m parameter to a perspective projection.
  * The current value of m is ignored
  * This does NOT make any OpenGL calls.
  */
GLS_EXPORT void GlsGetPerspective( GlsMatrixType& m,
    double                                        fovy,
    double                                        aspect,
    double                                        zNear,
    double                                        zFar );

// using a namespace to help avoid collisions with user code.  Future functionality should prefer to go here
namespace Util
{
    ////////////////////////////////////////////////////////////////////////////////
    /// Clamps a value to the range [min, max]
    /// \param val The value to clamp
    /// \param min The minimum value in the range
    /// \param max The maximum value in the range
    ////////////////////////////////////////////////////////////////////////////////
    template<class T>
    T Clamp( const T& val, const T& min, const T& max )
    {
        return std::min( max, std::max( min, val ) );
    }

    ////////////////////////////////////////////////////////////////////////////////
    /// Split a string and add to existing vector of elements with delimeters removed.
    /// \param s The string to split
    /// \param delim The delimiter to split the string on.
    /// \param elems The vector of elements to append each split string to.
    /// \param maxElems The maximum number of elements to split. Remaining elements
    ///                 are appended unsplit as the last value. If 0, it does not
    ///                 have a maximum.
    /// \note Adapted from http://stackoverflow.com/questions/236129/split-a-string-in-c
    ////////////////////////////////////////////////////////////////////////////////
    inline void Split( const std::string& s, const char delim, std::vector<std::string>& elems, const std::size_t maxElems = 0 )
    {
        std::istringstream ss( s );
        std::string        item;
        while( std::getline( ss, item, delim ) )
        {
            elems.push_back( DISTI_RVAL_MOVE( item ) );
            if( elems.size() == maxElems )
            {
                break;
            }
        }
        if( elems.size() == maxElems && ss.good() && maxElems > 0 )
        {
            std::string remainder;
            std::getline( ss, remainder, '\0' );
            elems.back() += delim + remainder;
        }
    }

    ////////////////////////////////////////////////////////////////////////////////
    /// Split a string return a vector of the elements with delimeters removed.
    /// \param s The string to split
    /// \param delim The delimiter to split the string on.
    /// \param maxElems The maximum number of elements to split. Remaining elements
    ///                 are appended unsplit as the last value. If 0, it does not
    ///                  have a maximum.
    /// \return The vector of split elements.
    /// \note Adapted from http://stackoverflow.com/questions/236129/split-a-string-in-c
    ////////////////////////////////////////////////////////////////////////////////
    inline std::vector<std::string> Split( const std::string& s, const char delim, const std::size_t maxElems = 0 )
    {
        std::vector<std::string> elems;
        Split( s, delim, elems, maxElems );
        return elems;
    }

    /// Passing null to std::string is not well-defined. Create a string safely.
    inline std::string MakeString( const char* const cStr )
    {
        return ( cStr ? cStr : "" );
    }
} // namespace Util

///////////////////////////////////////////////////////////////////////////////////////////////////
// Forward declarations for globals managed by GlsGlobals.
class GlsFontMan;
class IGlsStateManager;
class List_c;
class Mutex;
class TextureLoaderList;

/// Hold global objects so we can control order of destruction.
class GlsGlobals
{
public:
    /// Singleton instance
    GLS_EXPORT static GlsGlobals& Instance();

    /// Gets the image list. \sa GetImageListMutex()
    GLS_EXPORT List_c& GetImageList();

    /// Gets the mutex for protecting the image list. \sa GetImageList()
    GLS_EXPORT Mutex& GetImageListMutex();

    /// Gets the global font manager.
    GLS_EXPORT GlsFontMan& GetFontMan();

    /// Gets the global state manager instance
    GLS_EXPORT IGlsStateManager& GetStateManager();

    /// Gets the global list of texture loaders
    GLS_EXPORT TextureLoaderList& GetTextureLoaders();

private:
    // Order of objects is important here since they are destroyed in the reverse order listed
    ScopedPtr<List_c>            _imageList;
    ScopedPtr<Mutex>             _imageListMutex;
    ScopedPtr<GlsFontMan>        _fontMan;
    ScopedPtr<IGlsStateManager>  _stateManager;
    ScopedPtr<TextureLoaderList> _textureLoaders;

    GlsGlobals();
    GlsGlobals( const GlsGlobals& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const GlsGlobals& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

// Check that bitness matches detected value
namespace Detail
{
    // We need this function because 'static_assert' replacements for pre-C++11 compilers cannot be at file scope.
    inline void _checkPointerSize()
    {
        // clang-format off
        DISTI_STATIC_ASSERT_STR( ( DISTI_IS_BITNESS( 64 ) && sizeof( void* ) == 8 )
                              || ( DISTI_IS_BITNESS( 32 ) && sizeof( void* ) == 4 ),
            "Pointer size is unexpected for this bitness" );
        DISTI_STATIC_ASSERT_STR( DISTI_IS_BITNESS( 64 ) ^ DISTI_IS_BITNESS( 32 ), "Expected one bitness to be detected." );
        // clang-format on
    }
} // namespace Detail
} // namespace disti

// Our own local versions of a few glu methods to avoid needing to include the GL Utility library
GLS_EXPORT void glsPerspective( double fovy, double aspect, double zNear, double zFar );

#ifdef MATRIX_TYPE_FLOAT
GLS_EXPORT bool glsProject( double objx, double objy, double objz,
    const float modelMatrix[ 16 ],
    const float projMatrix[ 16 ],
    const int   viewport[ 4 ],
    double* winx, double* winy, double* winz );

GLS_EXPORT bool glsUnProject( double winx, double winy, double winz,
    const float modelMatrix[ 16 ],
    const float projMatrix[ 16 ],
    const int   viewport[ 4 ],
    double* objx, double* objy, double* objz );
#else
GLS_EXPORT bool  glsProject( double objx, double objy, double objz,
     const double modelMatrix[ 16 ],
     const double projMatrix[ 16 ],
     const int    viewport[ 4 ],
     double* winx, double* winy, double* winz );

GLS_EXPORT bool glsUnProject( double winx, double winy, double winz,
    const double modelMatrix[ 16 ],
    const double projMatrix[ 16 ],
    const int    viewport[ 4 ],
    double* objx, double* objy, double* objz );
#endif

#endif