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>
 
#    define _CRT_FUNCTIONS_REQUIRED 1
#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 ///< True macro, for backward compatibility purposes.
#endif
 
#ifndef FALSE
#    define FALSE 0 ///< False macro, for backward compatibility purposes.
#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;
 
const char PARSER_CLEARSTRING_DELIMETER_START[] = "#$STRING_START$#"; ///< Used for parsing lines of clear (multiline otherwise unencoded) text.
const char PARSER_CLEARSTRING_DELIMETER_END[]   = "#$STRING_END$#";   ///< Used for parsing lines of clear (multiline otherwise unencoded) text.
 
const double HIT_TOLERANCE = 5.0; ///< The hit tolerance in logical units for selecting objects in the editor.
 
/// Determines if x is included in the range x1 to x2.
/// \param x The value to check.
/// \param x1 The minimum range.
/// \param x2 The maximum range.
/// \return Whether or not x is in the range.
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.
/// \param x The value to check.
/// \return True if x 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.
/// \param x The value to check.
/// \return True if x 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).
/// \param x The value to check.
/// \param threshold A small value near zero to check from.
/// \return True if x is closer to zero than threshold.
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).
/// \param x The value to check.
/// \return True if x is very close to zero.
template<class X>
bool VeryCloseToZero( X x ) { return CloseToZero( x, X( 0.0001 ) ); }
 
/// Determines if the argument is very small (< 10E-3).
/// \param x The value to check.
/// \return True if x is close to zero.
template<class X>
bool IsNearZero( X x ) { return CloseToZero( x, X( 0.001 ) ); }
 
/// \deprecated Renamed to IsNearZero().
/// \param x The value to check.
/// \return True if x is close to zero.
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.
/// \return The X.Y OpenGL version.
GLS_EXPORT float OpenGLVersion();
 
/// \return Whether or not the requested OpenGL extension is supported.
/// \param extension The string name of the extension to check.
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 ];
}
 
/// Allow the user to change the predefined colors.
/// \param index The index of the color to change.
/// \param red The new red channel value to set (0-255).
/// \param green The new green channel value to set (0-255).
/// \param blue The new blue channel value to set (0-255).
/// \param alpha The new alpha channel value to set (0-255).
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 for the underlying char type.
    typedef int            int_type;   ///< Typedef for the underlying int type.
    typedef std::streampos pos_type;   ///< Typedef for the underlying stream position type.
    typedef std::streamoff off_type;   ///< Typedef for the underlying stream offset type.
    typedef std::mbstate_t state_type; ///< Typedef for the underlying multibyte conversion state type.
 
    /// \see std::char_traits::assign
    /// \param c1
    /// \param c2
    static void assign( char_type& c1, const char_type& c2 )
    {
        c1 = c2;
    }
 
    /// \see std::char_traits::eq
    /// \param c1
    /// \param c2
    /// \return
    static bool eq( const char_type& c1, const char_type& c2 )
    {
        return c1 == c2;
    }
 
    /// \see std::char_traits::lt
    /// \param c1
    /// \param c2
    /// \return
    static bool lt( const char_type& c1, const char_type& c2 )
    {
        return c1 < c2;
    }
 
    /// \see std::char_traits::compare
    /// \param s1
    /// \param s2
    /// \param n
    /// \return
    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 );
    }
 
    /// \see std::char_traits::length
    /// \param s
    /// \return
    static size_t length( const char_type* s )
    {
        size_t x = 0u;
        while( *s++ )
        {
            ++x;
        }
        return ( x );
    }
 
    /// \see std::char_traits::find
    /// \param s
    /// \param n
    /// \param a
    /// \return
    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;
    }
 
    /// \see std::char_traits::move
    /// \param s1
    /// \param s2
    /// \param n
    /// \return
    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 ) ) );
    }
 
    /// \see std::char_traits::copy
    /// \param s1
    /// \param s2
    /// \param n
    /// \return
    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 ) ) );
    }
 
    /// \see std::char_traits::assign
    /// \param s
    /// \param n
    /// \param a
    /// \return
    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 );
    }
 
    /// \see std::char_traits::to_char_type
    /// \param c
    /// \return
    static char_type to_char_type( const int_type& c )
    {
        return static_cast<char_type>( c );
    }
 
    /// \see std::char_traits::to_int_type
    /// \param c
    /// \return
    static int_type to_int_type( const char_type& c )
    {
        return static_cast<int_type>( c );
    }
 
    /// \see std::char_traits::eq_int_type
    /// \param c1
    /// \param c2
    /// \return
    static bool eq_int_type( const int_type& c1, const int_type& c2 )
    {
        return c1 == c2;
    }
 
    /// \see std::char_traits::eof
    /// \return
    static int_type eof()
    {
        return static_cast<int_type>( EOF );
    }
 
    /// \see std::char_traits::not_eof
    /// \param c
    /// \return
    static int_type not_eof( const int_type& c )
    {
        return ( c == eof() ) ? 0 : c;
    }
};
 
typedef std::basic_string<unsigned short, CharTraitsUnsignedShort> UTF16String;          ///< A cross platform UTF-16 encoded string.
typedef std::ofstream                                              UTF16Outfilestream;   ///< A cross platform UTF-16 encoded ofstream.
typedef std::ostream                                               UTF16Outstream;       ///< A cross platform UTF-16 encoded ostream.
typedef std::string                                                UnicodeString;        ///< A cross platform UTF-8 encoded string.
typedef std::ofstream                                              UnicodeOutfilestream; ///< A cross platform UTF-8 encoded ofstream.
typedef std::ostream                                               UnicodeOutstream;     ///< A cross platform UTF-8 encoded string.
 
#else
 
typedef std::wstring   UTF16String;          ///< A cross platform UTF-16 encoded string.
typedef std::wofstream UTF16Outfilestream;   ///< A cross platform UTF-16 encoded ofstream.
typedef std::wostream  UTF16Outstream;       ///< A cross platform UTF-16 encoded ostream.
typedef std::wstring   UnicodeString;        ///< A cross platform UTF-8 encoded string.
typedef std::wofstream UnicodeOutfilestream; ///< A cross platform UTF-8 encoded ofstream.
typedef std::wostream  UnicodeOutstream;     ///< A cross platform UTF-8 encoded string.
 
#endif
 
/// Convert the given UTF8 string to UTF16.
/// \param src The 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.
/// \return True if the numbers are close enough to be considered equal.
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.
/// \param x The first object to compare.
/// \param y The second object to compare.
/// \note 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.
/// \param x The first object to compare.
/// \param y The second object to compare.
/// \note 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.
/// \param x The first object to compare.
/// \param y The second object to compare.
/// \param pr The function to serve as the predicate.
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.
/// \param x The first object to compare.
/// \param y The second object to compare.
/// \param pr The function to serve as the predicate.
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;  ///< The viewport matrix.
    GlsMatrixType* projMatrix;  ///< The projection matrix.
    GlsMatrixType* modelMatrix; ///< The modelview matrix.
 
    /// Default constructor.
    /// Keeps everything NULL.
    GLS_EXPORT OpenGLMatrices();
 
    /// Copy constructor.
    /// \note Pointers are copied as-is, copies of the data are NOT made.
    /// \param src The object to copy from.
    GLS_EXPORT OpenGLMatrices( const OpenGLMatrices& src );
 
    /// Another constructor.
    /// \note Pointers are copied as-is, copies of the data are NOT made.
    /// \param view The viewport matrix to use.
    /// \param proj The projection matrix to use.
    /// \param model The modelview matrix to use.
    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;
}
 
/// 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.
/// \param result The returned transformation matrix to the new coordinate system.
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 );
 
/// \param frame The DisplayFrame to start at.
/// \return 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).
/// \param a The first point to check.
/// \param b The second point to check.
/// \param c The third point to check.
/// \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.
/// \return 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.
/// \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.
/// \return true If the vertices were found.
/// \return false  If there are not three non-colinear vertices in the array
///                 if this occurs, the index values are undefined.
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.
/// \param object the object whose texture points are to be calculated
/// \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 );
 
/// \return A minimum length for a call to EncodeString.
/// \note 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;     ///< The width in pixels.
    int            height;    ///< The height in pixels.
    int            comprSize; ///< The size in bytes.
    unsigned char* pixels;    ///< Pointer to the underlying data buffer.
} InlinePixmap;
 
/// Make the incoming path relative to another path.
/// \param originalPath The path to make relative.
/// \param relativePath The path to make the path relative from.
/// \return The resulting relative path, or empty string if not possible.
GLS_EXPORT char* MakeRelativePath( const char* originalPath, const char* relativePath );
 
/// Converts backslashes to forward slashes in the given string.
/// \param str A pointer to a string that is changed in place.
GLS_EXPORT void ConvertBackslashToSlash( char* str );
 
/// Converts backslashes to forward slashes in the given string.
/// \param str Reference to a string that is changed in place.
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);
/// \param num The number of ranges.
/// \param val The value to test.
/// \return True if the value is within any of the ranges.
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.
/// \param filename The name of the file to open.
/// \param flags fopen style file arguments (e.g. "r").
/// \param outstr The stream to write to.
/// \return True if the operation was successful.
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.
/// \return The appropriate resulting resolved path, prepended with the resource path.
GLS_EXPORT std::string ResolvePath( const char* path );
 
/// Helper method taking a std::string.
/// \param path The relative path to resolve
/// \return The appropriate resulting resolved path, prepended with the resource path.
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 );
 
/// \return True if the file exists, false otherwise.
/// \param filename The filename to check.
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 );
 
/// \return True if the file exists and is a directory, false otherwise.
/// \param filename The filename to check.
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 );
 
/// \return The file name from a filename with path.
/// \note This does not allocate new memory, but rather just returns a pointer inside the original string.
/// \param path The path to return the file (base) name from.
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.
/// \param path The path to return the file (base) name from.
/// \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 );
 
/// \return Whether or not the incoming string contains something other than whitespace.
/// \param val The string to check.
GLS_EXPORT bool ContainsNonBlank( const std::string& val );
 
/// Read bytes from the incoming file, excluding spaces.
/// \param f The file to read from.
/// \param result A pointer to storage to contain the result modified in place.
/// \param maxLen The length of the memory allocated to result in bytes.
/// \return True if operation was successful.
GLS_EXPORT bool GetNoSpaces( FILE* f, char* result, int maxLen );
 
/// Reads to the next end of line and stores the result.
/// \param instr The stream to read from.
/// \param result The string reference to write the result to.
/// \param decode Whether or not to decode the string.
/// \return True if successful.
GLS_EXPORT bool GetToEnd( std::istream& instr, std::string& result, bool decode );
 
/// Reads a Vertex from the stream.
/// \param instr The stream to read from.
/// \param vert The Vertex pointer to write the result to.
/// \param getColor Whether or not to parse the color also.
/// \return True if successful.
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.
/// \param dllFileName The path of the binary to search.
/// \param nameList The returned list of relevant symbol names.
/// \param createClassTag The symbol prefix to search for.
/// \return 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 shared library and attempts to run GlsDefaultClassName(), if found.
/// \param dllFileName The file name of the shared library to search in.
/// \return The located class name, or 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 )
/// Opens a native WIN32 open file dialog on Windows, a FLTK dialog on other platforms.
/// \param win The FLTK window to open the dialog on top of.
/// \param filePath The initially selected / returned file.
/// \param filePathSize The size of the filePath buffer in bytes.
/// \param directory The initially selected / returned directory.
/// \param filterStr The file type filter string.
/// \param defaultExt The default file extension.
/// \param title The window title for the dialog.
/// \param multiSelect Whether or not to allow multiple files to be selected.
/// \param createFile Whether or not the dialog will allow a new file to be created.
/// \param fileMustExist Whether or not the specified file must already exist.
/// \param pathMustExist Whether or not the specified directory must already exist.
/// \param noChangeDirectory Whether or not the dialog will allow the user to change CWD.
/// \return True if a file was located successfully.
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 );
 
/// Opens a native WIN32 save file dialog on Windows, a FLTK dialog on other platforms.
/// \param win The FLTK window to open the dialog on top of.
/// \param filePath The initially selected / returned file.
/// \param filePathSize The size of the filePath buffer in bytes.
/// \param directory The initially selected / returned directory.
/// \param filterStr The file type filter string.
/// \param defaultExt The default file extension.
/// \param title The window title for the dialog.
/// \param createFile Whether or not the dialog will allow a new file to be created.
/// \param fileMustExist Whether or not the specified file must already exist.
/// \param pathMustExist Whether or not the specified directory must already exist.
/// \param noChangeDirectory Whether or not the dialog will allow the user to change CWD.
/// \return True if a file was located successfully.
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
 
/// Checks the OpenGL error state, and prints to stdout if there was an error.
GLS_EXPORT void CheckGLError();
 
//---------------------------------------------------------------------------
/**
  * 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 );
 
/// Substitutes environment variables for their actual values in the incoming path.
/// \param originalPath Path to substitute environment variables.
/// \return The string with environment variables replaced with their actual paths.
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();
 
    /// Parses the command line and takes action accordingly.
    /// \param argc The number of arguments.
    /// \param argv The array of arguments.
    GLS_EXPORT void ReadCommandLine( int argc, char** argv );
 
    /// Prints the usage instructions for the command line operations to stdout.
    GLS_EXPORT void Usage();
 
    int    _argc; ///< The number of arguments.
    char** _argv; ///< The array of arguments.
 
    /// \return Whether or not the app should run in silent mode.
    bool SilentMode() const { return _silentMode; }
 
    /// \return The glsCommandLine singleton instance.
    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();
 
    /// Constructor
    /// \param code Method name only.
    /// \param usage Full method signature.
    /// \param comment Associated comment.
    GLS_EXPORT InterfaceDescriptionClass( const char* code, const char* usage, const char* comment );
 
    GLS_EXPORT ~InterfaceDescriptionClass();
 
    /// Copy constructor
    /// \param source The object to copy from.
    GLS_EXPORT InterfaceDescriptionClass( const InterfaceDescriptionClass& source );
 
    /// Assignment constructor
    /// \param source The object to copy from.
    /// \return The resulting object (this).
    GLS_EXPORT InterfaceDescriptionClass& operator=( const InterfaceDescriptionClass& source );
 
    /// Set the code member to a new value.
    GLS_EXPORT void Code( const char* );
 
    /// Set the usage member to a new value.
    GLS_EXPORT void Usage( const char* );
 
    /// Set the comment member to a new value.
    GLS_EXPORT void Comment( const char* );
 
    /// \return The current code member.
    const char* Code() const { return _code; }
 
    /// \return The current usage member.
    const char* Usage() const { return _usage; }
 
    /// \return The current comment member.
    const char* Comment() const { return _comment; }
 
#if defined( DISTI_HAS_RVAL_REFS )
    /// Move constructor
    /// \param source The object to move from.
    InterfaceDescriptionClass( InterfaceDescriptionClass&& source )
        : _code( NULL )
        , _usage( NULL )
        , _comment( NULL )
    {
        StealFrom( source );
    }
 
    /// Assignment move operator
    /// \param source The object to move from.
    /// \return The resulting object (this).
    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; ///< Typedef for a list of interface description objects.
 
/** 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 shorthand for std::ostream.
    typedef std::istream istreamType; ///< Typedef shorthand for std::istream.
 
    /// This function serializes itself into the provided stream object.
    /// \param outstr This is the object used by the GlsMultiVal class to serialize itself onto.
    virtual void StreamOut( ostreamType& outstr ) const = 0;
 
    /// 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.
    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;  ///< The first value.
    T2  _val2;  ///< The second value.
    T3  _val3;  ///< The third value.
    T4  _val4;  ///< The fourth value.
    T5  _val5;  ///< The fifth value.
    T6  _val6;  ///< The sixth value.
    T7  _val7;  ///< The seventh value.
    T8  _val8;  ///< The eighth value.
    T9  _val9;  ///< The ninth value.
    T10 _val10; ///< The tenth value.
 
    /** 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.
    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 Second value to use for intialization of type T2.
    /// \param val3 Third value to use for intialization of type T3.
    /// \param val4 Fourth value to use for intialization of type T4.
    /// \param val5 Fifth value to use for intialization of type T5.
    /// \param val6 Sixth value to use for intialization of type T6.
    /// \param val7 Seventh value to use for intialization of type T7.
    /// \param val8 Eighth value to use for intialization of type T8.
    /// \param val9 Ninth value to use for intialization of type T9.
    /// \param val10 Tenth value to use for intialization of type T10.
    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();
    }
 
    /// Equality operator
    /// \param val The object to compare against.
    /// \return True if the objects are equal.
    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;
    }
 
    /// Inequality operator
    /// \param val The object to compare against.
    /// \return True if the objects are not equal.
    virtual bool operator!=( const GlsMultiVal& val ) const
    {
        return !( *this == val );
    }
 
    virtual void StreamOut( ostreamType& outstr ) const DISTI_METHOD_OVERRIDE
    {
        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;
    }
 
    virtual void StreamIn( istreamType& instr ) DISTI_METHOD_OVERRIDE
    {
        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;
        }
    }
};
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param multiVal The value to write to the stream.
/// \return The stream in its current state.
GLS_EXPORT std::ostream& operator<<( std::ostream& outstr, const GlsMultiValBase& multiVal );
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param multiVal The returned value read from the stream.
/// \return The stream in its current state.
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; ///< The underlying wrapped string.
 
    /// Default constructor. Creates an empty GlsPropString.
    GlsPropString()
        : _string( "" )
    {
    }
 
    /// Create a new GlsPropString using the provided std string.
    /// \param str The std::string to use to create the GlsPropString.
    GlsPropString( const std::string& str )
        : _string( str )
    {
    }
 
    /// Create a new GlsPropString using the provided C-style string.
    /// \param str The C-style string to use to create the GlsPropString.
    GlsPropString( const char* str )
        : _string( str ? str : "" )
    {
    }
 
    /// \return The underlying string value for this object.
    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.
    /// \param str1 One object to compare.
    /// \param str2 The other object to compare.
    /// \return True if the objects are equal.
    friend inline bool operator==( const GlsPropString& str1, const GlsPropString& str2 )
    {
        return str1._string == str2._string;
    }
 
    /// Checks lexicographic inequality of the two arguments.
    /// \param str1 One object to compare.
    /// \param str2 The other object to compare.
    /// \return True if the objects are not equal.
    friend inline bool operator!=( const GlsPropString& str1, const GlsPropString& str2 )
    {
        return !( str1 == str2 );
    }
};
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param str The value to write to the stream.
/// \return The stream in its current state.
inline std::ostream& operator<<( std::ostream& outstr, const GlsPropString& str )
{
    outstr << disti::C_EncodeString( str._string );
    return outstr;
}
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param str The returned value read from the stream.
/// \return The stream in its current state.
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; ///< The underlying wrapped string.
 
    /// Default constructor, create an empty GlsPropStringQuoted object.
    GlsPropStringQuoted()
    {
    }
 
    /// Constructor, create a new GlsPropStringQuoted object using the provided std::string object.
    /// \param str The std::string object to use to create the GlsPropStringQuoted object
    GlsPropStringQuoted( const std::string& str )
        : _string( str )
    {
    }
 
    /// Constructor, create a new GlsPropStringQuoted object using the provided C-style string.
    /// \param str the C-style string to use to create the GlsPropStringQuoted object.
    GlsPropStringQuoted( const char* str )
        : _string( str )
    {
    }
 
    /// \return The underlying string value for this object.
    operator std::string() const
    {
        return _string;
    }
 
    /// \return The underlying string value for this object.
    std::string& String()
    {
        return _string;
    }
 
    /// Equality operator
    /// \param str The object to compare.
    /// \return True if the objects are equal.
    bool operator==( const GlsPropStringQuoted& str ) const
    {
        return str._string == _string;
    }
};
 
/// Stream out operator
/// \param outstr The stream to write to.
/// \param str The value to write to the stream.
/// \return The stream in its current state.
inline std::ostream& operator<<( std::ostream& outstr, const GlsPropStringQuoted& str )
{
    outstr << '\"' << disti::C_EncodeString( str._string ) << '\"';
    return outstr;
}
 
/// Stream in operator
/// \param instr The stream to read from.
/// \param str The returned value read from the stream.
/// \return The stream in its current state.
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
/// Open the default web browser and go to the specified URL.
/// \param url The URL to navigate to.
void SpawnBrowser( const char* url );
#endif
 
/// Call this to check for the availability of a DiSTI controlled 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.
/// \return true if the license is available
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.
/// \param m The matrix to hold the resulting orthographic projection.
/// \param left The left side coordinate.
/// \param right The right side coordinate.
/// \param bottom The bottom side coordinate.
/// \param top The top side coordinate.
/// \param zNear The near clipping coordinate.
/// \param zFar The far clipping coordinate.
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.
/// \param m The matrix to hold the resulting perspective projection.
/// \param fovy The vertical FOV in degrees.
/// \param aspect The aspect ratio.
/// \param zNear The near clipping distance.
/// \param zFar The far clipping distance.
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.
    /// \return The value clamped between min and max.
    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( maxElems > 0 && elems.size() == maxElems && ss.good() )
        {
            std::string remainder;
            std::getline( ss, remainder, '\0' );
            elems.back() += delim + remainder;
        }
        else if( s.size() && s.at( s.size() - 1 ) == delim )
        {
            // Handle the case where the last item is an empty string.
            elems.push_back( "" );
        }
    }
 
    /// 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. Creates a string safely.
    /// \param cStr The string to create a std::string from.
    /// \return A std::string created from the incoming C string.
    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:
    /// \return The GlsGlobals singleton instance.
    GLS_EXPORT static GlsGlobals& Instance();
 
    /// \return The image list.
    /// \sa GetImageListMutex()
    GLS_EXPORT List_c& GetImageList();
 
    /// \return The mutex for protecting the image list.
    /// \sa GetImageList()
    GLS_EXPORT Mutex& GetImageListMutex();
 
    /// \return The global font manager.
    GLS_EXPORT GlsFontMan& GetFontMan();
 
    /// \return The global state manager instance.
    GLS_EXPORT IGlsStateManager& GetStateManager();
 
    /// \return 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
/// Set up a perspective projection. Functions the same as gluPerspective().
/// \param fovy The vertical FOV in degrees.
/// \param aspect The aspect ratio.
/// \param zNear The near clipping distance.
/// \param zFar The far clipping distance.
GLS_EXPORT void glsPerspective( double fovy, double aspect, double zNear, double zFar );
 
/// Projects a point from object space into window space. Functions the same as gluProject().
/// \param objx The X coordinate to project.
/// \param objy The Y coordinate to project.
/// \param objz The Z coordinate to project.
/// \param modelMatrix The modelview matrix to project with.
/// \param projMatrix The projection matrix to project with.
/// \param viewport The viewport to project with.
/// \param winx The returned projected X coordinate.
/// \param winy The returned projected Y coordinate.
/// \param winz The returned projected Z coordinate.
/// \return True if the operation was successful.
#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 );
#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 );
#endif
 
/// Unprojects a point from window space into object space. Functions the same as gluUnproject().
/// \param winx The X coordinate to unproject.
/// \param winy The Y coordinate to unproject.
/// \param winz The Z coordinate to unproject.
/// \param modelMatrix The modelview matrix to project with.
/// \param projMatrix The projection matrix to project with.
/// \param viewport The viewport to project with.
/// \param objx The returned unprojected X coordinate.
/// \param objy The returned unprojected Y coordinate.
/// \param objz The returned unprojected Z coordinate.
/// \return True if the operation was successful.
#ifdef MATRIX_TYPE_FLOAT
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  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