dnc_util.h

Go to the documentation of this file.

/*! \file
  \brief  DNC related utility data types and constants

  \par Copyright Information

  Copyright (c) 2017 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 _DNC_UTIL_H
#define _DNC_UTIL_H

#include <math.h>
#if defined( _WIN32 )
#    include <windows.h>
#else
#    define CALLBACK
#endif // _WIN32
#include "gls_font_base.h"
#include "vpf_data_value.h"
#include "vpf_util.h"
#include <GL/gl.h>
#include <GL/glu.h>

namespace disti
{
// forward ref
class GlsFontRenderer;
class DNCFacePrimTable;
class DNCRingTable;
class DNCEdgePrimTable;

/** collection of DNC related utility data types and constants */
class DNCUtil
{
public:
    static const char* const NOTES_JOIN_TABLE_EXT;   /**< file extension for notes join table file */
    static const char* const FEATURE_ID_COLUMN_NAME; /**< column name for feature ID */
    static const char* const RAT_ID_COLUMN_NAME;     /**< column name for related attribute table ID */
    static const char* const FAC_ID_COLUMN_NAME;     /**< column name of face id in an area join table */

    static const char* const CULTURAL_LANDMARKS_COVERAGE_NAME;  /**< name of "Cultural Landmarks" coverage */
    static const char* const EARTH_COVER_COVERAGE_NAME;         /**< name of "Earth Cover" coverage */
    static const char* const ENVIRONMENT_COVERAGE_NAME;         /**< name of "Environment" coverage */
    static const char* const HYDROGRAPHY_COVERAGE_NAME;         /**< name of "Hydrography" coverage */
    static const char* const INLAND_WATERWAYS_COVERAGE_NAME;    /**< name of "Inland Waterways" coverage */
    static const char* const LAND_COVER_COVERAGE_NAME;          /**< name of "Land Cover" coverage */
    static const char* const AIDS_TO_NAVIGATION_COVERAGE_NAME;  /**< name of "Aids to Navigation" coverage */
    static const char* const OBSTRUCTIONS_COVERAGE_NAME;        /**< name of "Obstructions" coverage */
    static const char* const PORT_FACILITIES_COVERAGE_NAME;     /**< name of "Port Facilities" coverage */
    static const char* const RELIEF_COVERAGE_NAME;              /**< name of "Relief" coverage */
    static const char* const DATA_QUALITY_COVERAGE_NAME;        /**< name of "Data Quality" coverage */
    static const char* const COASTLINE_COUNTRIES_COVERAGE_NAME; /**< name of "Coastline/Countries" coverage */
    static const char* const LIMITS_COVERAGE_NAME;              /**< name of "Limits" coverage */

    static const char* const ADMIN_LINE_FEATURE_NAME;    /**< name of "Administrative lines" line features */
    static const char* const AERO_POINT_FEATURE_NAME;    /**< name of "Aeronautical Points" point features */
    static const char* const AQUEDCT_LINE_FEATURE_NAME;  /**< name of "Aqueduct lines" line features */
    static const char* const BARRIER_LINE_FEATURE_NAME;  /**< name of "Barrier lines" line features */
    static const char* const BERTH_POINT_FEATURE_NAME;   /**< name of "Berth points" point features */
    static const char* const BOTCHAR_POINT_FEATURE_NAME; /**< name of "Bottom Characteristic Point Features" point features */
    static const char* const BOUNDRY_LINE_FEATURE_NAME;  /**< name of "Boundary" line features */
    static const char* const BRIDGE_AREA_FEATURE_NAME;   /**< name of "Bridge" area features */
    static const char* const BRIDGE_LINE_FEATURE_NAME;   /**< name of "Bridge/Overpass" line features */
    static const char* const BRIDGSP_AREA_FEATURE_NAME;  /**< name of "Bridge Span" area features */
    static const char* const BRIDGSP_LINE_FEATURE_NAME;  /**< name of "Bridge Span" line features */
    static const char* const BUILDNG_AREA_FEATURE_NAME;  /**< name of "Building Areas" area features */
    static const char* const BUILDNG_POINT_FEATURE_NAME; /**< name of "Building points" point features */
    static const char* const BUILTUP_POINT_FEATURE_NAME; /**< name of "Built-up area points" point features */
    static const char* const BUOYBCN_POINT_FEATURE_NAME; /**< name of "Buoy/Beacon Point Feature Table" point features */
    static const char* const CALLIN_POINT_FEATURE_NAME;  /**< name of "Calling In points" point features */
    static const char* const CANAL_AREA_FEATURE_NAME;    /**< name of "Canal areas" area features */
    static const char* const CANAL_LINE_FEATURE_NAME;    /**< name of "Canal lines" line features */
    static const char* const COAST_LINE_FEATURE_NAME;    /**< name of "Coastline lines" line features */
    static const char* const COMM_POINT_FEATURE_NAME;    /**< name of "Communications points" point features */
    static const char* const CURRDIA_POINT_FEATURE_NAME; /**< name of "Current Diagram Points" point features */
    static const char* const CURRFL_POINT_FEATURE_NAME;  /**< name of "Current Flow Points" point features */
    static const char* const DAM_LINE_FEATURE_NAME;      /**< name of "Dam lines" line features */
    static const char* const DANGER_AREA_FEATURE_NAME;   /**< name of "Discolored Water/Foul Ground" area features */
    static const char* const DANGER_POINT_FEATURE_NAME;  /**< name of "Breakers/Discolored Water" point features */
    static const char* const DQY_AREA_FEATURE_NAME;      /**< name of "Data Quality Areas" area features */
    static const char* const ECR_AREA_FEATURE_NAME;      /**< name of "Earth Cover areas" area features */
    static const char* const ECR_TEXT_FEATURE_NAME;      /**< name of "Earth Cover texts" text features */
    static const char* const EMBANK_AREA_FEATURE_NAME;   /**< name of "Embankment areas" area features */
    static const char* const ENV_AREA_FEATURE_NAME;      /**< name of "Environment Areas" area features */
    static const char* const FENCE_LINE_FEATURE_NAME;    /**< name of "Fence lines" line features */
    static const char* const FISHHAT_AREA_FEATURE_NAME;  /**< name of "Fish Hatchery" area features */
    static const char* const FORESHO_AREA_FEATURE_NAME;  /**< name of "Foreshore areas" area features */
    static const char* const FORESHO_LINE_FEATURE_NAME;  /**< name of "Foreshore lines" line features */
    static const char* const FORESHO_POINT_FEATURE_NAME; /**< name of "Foreshore points" point features */
    static const char* const HAZARD_AREA_FEATURE_NAME;   /**< name of "Underwater Danger/Wreck" area features */
    static const char* const HAZARD_LINE_FEATURE_NAME;   /**< name of "Cable/Breakers" line features */
    static const char* const HAZARD_POINT_FEATURE_NAME;  /**< name of "Underwater Danger/Rock/Wreck" point features */
    static const char* const HYD_AREA_FEATURE_NAME;      /**< name of "Hydrography Area Features" area features */
    static const char* const HYD_LINE_FEATURE_NAME;      /**< name of "Hydrography Line Features" line features */
    static const char* const INDUST_AREA_FEATURE_NAME;   /**< name of "Industry areas" area features */
    static const char* const INDUST_POINT_FEATURE_NAME;  /**< name of "Industry points" point features */
    static const char* const ISLAND_POINT_FEATURE_NAME;  /**< name of "Island points" point features */
    static const char* const LAKE_AREA_FEATURE_NAME;     /**< name of "Lake areas" area features */
    static const char* const LANDING_AREA_FEATURE_NAME;  /**< name of "Landing areas" area features */
    static const char* const LANDING_POINT_FEATURE_NAME; /**< name of "Landing points" point features */
    static const char* const LANDMRK_AREA_FEATURE_NAME;  /**< name of "Landmark areas" area features */
    static const char* const LANDMRK_POINT_FEATURE_NAME; /**< name of "Landmark points" point features */
    static const char* const LCR_LINE_FEATURE_NAME;      /**< name of "Land Cover lines" line features */
    static const char* const LEADING_LINE_FEATURE_NAME;  /**< name of "Leading Lines" line features */
    static const char* const LIGHTS_LINE_FEATURE_NAME;   /**< name of "Lights Line Feature Table" line features */
    static const char* const LIGHTS_POINT_FEATURE_NAME;  /**< name of "Lights Point Feature Table" point features */
    static const char* const LIMBNDY_AREA_FEATURE_NAME;  /**< name of "Limit Boundaries" area features */
    static const char* const LIMBNDY_LINE_FEATURE_NAME;  /**< name of "Limit Boundaries" line features */
    static const char* const LOADING_AREA_FEATURE_NAME;  /**< name of "Offshore Loading Facility" area features */
    static const char* const LOADING_POINT_FEATURE_NAME; /**< name of "Loading Points" point features */
    static const char* const MARITIM_LINE_FEATURE_NAME;  /**< name of "Maritime Area" line features */
    static const char* const MARITIM_AREA_FEATURE_NAME;  /**< name of "Maritime Area" area features */
    static const char* const MARKER_POINT_FEATURE_NAME;  /**< name of "Marker Point Feature Table" point features */
    static const char* const MISCIWY_AREA_FEATURE_NAME;  /**< name of "Miscellaneous Inland Waterways areas" area features */
    static const char* const MOORING_POINT_FEATURE_NAME; /**< name of "Mooring points" point features */
    static const char* const OBSTRUC_AREA_FEATURE_NAME;  /**< name of "Obstruction Areas" area features */
    static const char* const OBSTRUC_POINT_FEATURE_NAME; /**< name of "Obstruction Points" point features */
    static const char* const ORCHARD_AREA_FEATURE_NAME;  /**< name of "Orchard" area features */
    static const char* const PARK_AREA_FEATURE_NAME;     /**< name of "Park areas" area features */
    static const char* const PARK_LINE_FEATURE_NAME;     /**< name of "Park lines" line features */
    static const char* const PIER_AREA_FEATURE_NAME;     /**< name of "Pier areas" area features */
    static const char* const PIER_LINE_FEATURE_NAME;     /**< name of "Pier lines" line features */
    static const char* const PIPE_LINE_FEATURE_NAME;     /**< name of "Pipeline Lines" line features */
    static const char* const POWER_LINE_FEATURE_NAME;    /**< name of "Power lines" line features */
    static const char* const POWER_POINT_FEATURE_NAME;   /**< name of "Power points" point features */
    static const char* const RAILRD_LINE_FEATURE_NAME;   /**< name of "Railroad lines" line features */
    static const char* const REEF_AREA_FEATURE_NAME;     /**< name of "Reef Areas" area features */
    static const char* const REL_LINE_FEATURE_NAME;      /**< name of "Relief lines" line features */
    static const char* const REL_POINT_FEATURE_NAME;     /**< name of "Relief points" point features */
    static const char* const RIVER_AREA_FEATURE_NAME;    /**< name of "River areas" area features */
    static const char* const RIVER_LINE_FEATURE_NAME;    /**< name of "River lines" line features */
    static const char* const ROUTE_AREA_FEATURE_NAME;    /**< name of "Route Maritime" area features */
    static const char* const ROUTE_LINE_FEATURE_NAME;    /**< name of "Route Maritime" line features */
    static const char* const RUINS_AREA_FEATURE_NAME;    /**< name of "Ruins areas" area features */
    static const char* const RUINS_POINT_FEATURE_NAME;   /**< name of "Ruins" point features */
    static const char* const SEAWALL_LINE_FEATURE_NAME;  /**< name of "Seawall lines" line features */
    static const char* const SECTOR_AREA_FEATURE_NAME;   /**< name of "Sector Areas" area features */
    static const char* const SNOWICE_AREA_FEATURE_NAME;  /**< name of "Snow/Ice" area features */
    static const char* const SNOWICE_POINT_FEATURE_NAME; /**< name of "Snow/Ice" point features */
    static const char* const SOUND_POINT_FEATURE_NAME;   /**< name of "Soundings Point Features" point features */
    static const char* const STRUCTR_AREA_FEATURE_NAME;  /**< name of "Structure areas" area features */
    static const char* const STRUCTR_LINE_FEATURE_NAME;  /**< name of "Structure lines" line features */
    static const char* const TIDE_POINT_FEATURE_NAME;    /**< name of "Tide Points" point features */
    static const char* const TRANS_AREA_FEATURE_NAME;    /**< name of "Transportation Areas" area features */
    static const char* const TRANS_LINE_FEATURE_NAME;    /**< name of "Transportation lines" line features */
    static const char* const TREE_AREA_FEATURE_NAME;     /**< name of "Tree areas" area features */
    static const char* const TREE_POINT_FEATURE_NAME;    /**< name of "Tree points" point features */
    static const char* const TUNNEL_LINE_FEATURE_NAME;   /**< name of "Tunnel Lines" line features */
    static const char* const VOLCANO_AREA_FEATURE_NAME;  /**< name of "Volcano" area features */

    static const char* const BROWSE_LIB_AREA_FEAT_NAME;       /**< name of browse library area features in the browse lib coverage */
    static const char* const BROWSE_LIB_AREA_FEAT_TABLE_NAME; /**< name of browse library area features table in the browse lib coverage */
    static const char* const BROWSE_LIB_AREA_JOIN_TABLE_NAME; /**< name of browse library area join table in the browse lib coverage */
    static const char* const BROWSE_LIB_AREA_JOIN_TABLE_KEY;  /**< name of key column in area join table in the browse lib coverage */

    /** lat lon aligned region */
    struct GeoRegion
    {
        VPFUtil::Coord2DLong swCorner; /**< southwest corner */
        VPFUtil::Coord2DLong neCorner; /**< northeast corner */
    };

    /** helper struct for storing/inputing edge vertices in a format suitable for the glu Tessellator */
    struct GLdoubleEdge
    {
        GLdouble* verts; /**< array of ( x,y,z ) verts else NULL */

        /** Ctor - single coordinate edge
        * \param x x coordinate
        * \param y y coordinate
        * \param z z coordinate
        */
        GLdoubleEdge( const double x, const double y, const double z )
        {
            // allocate one vert
            verts = new GLdouble[ 3u ];
            // store vert
            if( NULL != verts )
            {
                verts[ 0u ] = x;
                verts[ 1u ] = y;
                verts[ 2u ] = z;
            }
        }

        /** Ctor
        * \param edgCoords edge coordinates for new edge ( must be array of VPFUtil::DATA_TYPE_2D_COORD_SHORT )
        * \param reverseCoords true to store edge coordinates in reverse order else false
        */
        GLdoubleEdge( const VPFDataValue& edgCoords, const bool reverseCoords )
        {
            // get number of coords in edge and allocate array for verts
            const unsigned int numCoords = edgCoords.GetValueCount();
            verts                        = new GLdouble[ numCoords * 3u ];
            if( NULL != verts )
            {
                // get array of 2D coords from edgCoords
                const VPFUtil::Coord2DShort* const coords = edgCoords.GetCoord2DShortValues();

                // store in reverse direction?
                if( reverseCoords )
                {
                    // store new verts
                    for( unsigned int coordIndex = numCoords, vertIndex = 0u; coordIndex > 0u; --coordIndex )
                    {
                        verts[ vertIndex++ ] = coords[ coordIndex - 1u ].x;
                        verts[ vertIndex++ ] = coords[ coordIndex - 1u ].y;
                        verts[ vertIndex++ ] = 0.0;
                    }
                }
                else
                {
                    // store new verts in forward direction
                    for( unsigned int coordIndex = 0u, vertIndex = 0u; coordIndex < numCoords; ++coordIndex )
                    {
                        verts[ vertIndex++ ] = coords[ coordIndex ].x;
                        verts[ vertIndex++ ] = coords[ coordIndex ].y;
                        verts[ vertIndex++ ] = 0.0;
                    }
                }
            }
        }

        /** Dtor */
        ~GLdoubleEdge()
        {
            // kill verts as needed
            if( NULL != verts )
            {
                delete[] verts;
                verts = NULL;
            }
        }
    };

    /** array of GLdoubleEdge pointers */
    typedef VPFUtil::PointerArray<GLdoubleEdge> GLdoubleEdgeArray;

    /** one triangle of an area ( CCW winding ) */
    struct Tri
    {
        VPFUtil::Coord2DLong p1; /**< first point of tri */
        VPFUtil::Coord2DLong p2; /**< second point of tri */
        VPFUtil::Coord2DLong p3; /**< third point of tri */

        /** Get the area of the triangle
          * \return area of the triangle
          */
        inline double GetArea( void ) const
        {
            // Heron's formula
            const double a = sqrt( ( ( p1.x - p2.x ) * ( p1.x - p2.x ) ) + ( ( p1.y - p2.y ) * ( p1.y - p2.y ) ) );
            const double b = sqrt( ( ( p2.x - p3.x ) * ( p2.x - p3.x ) ) + ( ( p2.y - p3.y ) * ( p2.y - p3.y ) ) );
            const double c = sqrt( ( ( p3.x - p1.x ) * ( p3.x - p1.x ) ) + ( ( p3.y - p1.y ) * ( p3.y - p1.y ) ) );
            const double s = ( ( a + b + c ) / 2.0 );
            return ( sqrt( s * ( s - a ) * ( s - b ) * ( s - c ) ) );
        }

        /**  Determine if the given point falls within the triangle.  NOTE: algorithm requires that triangle
          * is wound CCW 
          * \param p point in question
          * \return true if point falls within triangle else false
          */
        inline bool PointTest( const VPFUtil::Coord2DLong& p ) const
        {
            return ( ( ( ( p.x - p1.x ) * ( -p3.y + p1.y ) + ( p.y - p1.y ) * ( p3.x - p1.x ) ) < 0.0 ) && ( ( ( p.x - p2.x ) * ( -p1.y + p2.y ) + ( p.y - p2.y ) * ( p1.x - p2.x ) ) <= 0.0 ) && ( ( ( p.x - p2.x ) * ( -p3.y + p2.y ) + ( p.y - p2.y ) * ( p3.x - p2.x ) ) >= 0.0 ) );
        }
    };

    /** array of triangle pointers */
    typedef VPFUtil::PointerArray<Tri> TriArray;

    /** font renderer helper class for rendering text features */
    class FontRenderer
    {
    public:
        /** Ctor
          * \param font font to render else NULL for default font
          * \param forceUpload true to force the font texture to be uploaded to GL (if it is not already uploaded)
          */
        FontRenderer( GlsFontBase* font, const bool forceUpload );

        /** Dtor */
        ~FontRenderer();

        /** Get the font attached to the renderer */
        GlsFontBase* GetFont( void ) { return ( _font ); }

        /** Initializes the font to begin rendering characters. This will set up
          * Open GL texture modes, bind the font's texture, set up minification
          * and magnification filters, etc.  This must be called before 
          * using any of the Render methods draw characters.
          */
        void InitRendering( void );

        /** Restores the Open GL state as it was before the call to InitRendering.
          * This should be called after all characters have been rendered using
          * the Render methods.
          */
        void TermRendering( void );

        /** Render a single proportional character
          * NOTE: assumes that a glBegin( GL_QUADS ) has been called
          * \param c character to render
          * \param pen_position_x x position of lower left of character
          * \param pen_position_y y position of lower left of character
          * \param char_size_ratio_x x size ratio
          * \param char_size_ratio_y y size ration
          * \param scale character scale
          * \param fgColor color for character
          */
        void RenderProportionalChar( const GlsFontBase::Char_t c, const float pen_position_x, const float pen_position_y,
            const float char_size_ratio_x, const float char_size_ratio_y,
            const GLfloat scale, const glsColor& fgColor );

    protected:
        GlsFontRenderer* _fontRenderer; /**< gls font renderer */
        GlsFontBase*     _font;         /**< font being rendered */

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

    /** encapsulates an array of Feature and Attribute Coding Catalog codes ( see MIL-PRF-89023 ) describing
      * the set of FACC codes used by a feature class*/
    class FACCArray
    {
    public:
        /** a FACC array entry */
        struct FACC
        {
            char         facc[ VPFUtil::FACC_CODE_LENGTH + 1u ]; /**< FACC code (plus one for terminator) */
            unsigned int faccIndex;                              /**< zero based index into value descriptor table for facc code */

            /** Ctor
              * \param newFacc facc code
              * \param newFaccIndex zero based index into value descriptor table for facc code 
              */
            FACC( const char* const newFacc, const unsigned int newFaccIndex )
            {
                // copy facc code
                facc[ 0u ] = '\0';
                if( NULL != newFacc )
                {
                    // copy the string
                    for( unsigned int i = 0; i < VPFUtil::FACC_CODE_LENGTH; i++ )
                    {
                        facc[ i ] = newFacc[ i ];
                    }
                    // force terminator
                    facc[ VPFUtil::FACC_CODE_LENGTH ] = '\0';
                }

                // copy index
                faccIndex = newFaccIndex;
            }
        };

        /** Ctor */
        FACCArray( void ){};

        /** Dtor */
        ~FACCArray(){};

        /** Determine if the array is valid
          * \return true if valid else false
          */
        bool IsValid( void ) const { return ( _faccs.IsValid() ); }

        /** Get the number of FACC codes in the array
          * \return number of FACC codes in the array
          */
        unsigned int GetCount( void ) const { return ( _faccs.GetCount() ); }

        /** Insert a FACC code into the array
          * \param facc code to insert (deep copied into array)
          * \param faccIndex zero based index into value descriptor table for facc code
          * \return true if success else false
          */
        bool InsertFACC( const char* const facc, const unsigned int faccIndex );

        /** Determine if the given FACC code is in the array
          * \param facc code in question
          * \return FACC if found else NULL
          */
        const FACC* FindFACC( const char* const facc ) const;

        /** Get the FACC code at the given index
          * \param faccIndex zero based index into array ( < GetCount() )
          * \return facc code else NULL
          */
        const FACC* GetFACC( const unsigned int faccIndex ) const { return ( _faccs.GetPointer( faccIndex ) ); }

    protected:
        VPFUtil::PointerArray<FACC> _faccs; /**< array of FACC pointers */

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

    /** helper class for a fixed value string */
    class DNCString
    {
    public:
        /** Ctor - deep copy given string - NOTE: string will be initialized to "" if src == NULL
          * \param src source string to copy
          * \param trimTrailingWS [optional, defaults to true] true to trim trailing whitespace when copying src else false
          */
        DNCString( const char* const src, const bool trimTrailingWS = true );

        /** Dtor */
        ~DNCString();

        /** Determine if the string is valid
          * \return true if valid else false
          */
        bool IsValid( void ) const { return ( _isValid ); }

        /** Get the string buffer (const)
          * \return string buffer (const) else NULL
          */
        operator const char*(void)const { return ( _str ); }

    protected:
        VPFUtil::WarningBool _isValid; /**< true if string is valid else false */
        char*                _str;     /**< allocated string buffer else NULL */

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

    /** encapsulates the results of a map query */
    class QueryResults
    {
    public:
        /** description of a feature in the query results */
        class FeatureDescription
        {
        public:
            /** encapsulates a feature attribute name and its value */
            class AttributePair
            {
            public:
                /** Ctor
                  * \param attribName name of feature attribute
                  * \param attribVal  value of feature attribute
                  */
                AttributePair( const char* const attribName, const char* const attribVal );

                /** Dtor */
                ~AttributePair();

                /** Determine if the attribute pair is valid
                  * \return true if valid else false
                  */
                bool IsValid( void ) const { return ( _isValid ); }

                /** Get the name of the feature attribute
                  * \return name of the feature attribute
                  */
                const char* GetName( void ) const { return ( _attribName ); }

                /** Get the value of the feature attribure
                  * \return value of the feature attribure
                  */
                const char* GetValue( void ) const { return ( _attribVal ); }

            protected:
                VPFUtil::WarningBool _isValid;    /**< true if attribute pair is valid else false */
                const DNCString      _attribName; /**< name of feature attribute */
                const DNCString      _attribVal;  /**< value of feature attribute */

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

            /** Ctor
              * \param covName name of coverage that contains this feature
              * \param featClassName name of feature class that contains this feature
              * \param faccCode FACC code for feature else NULL if feature does not use FACC codes
              * \param featIndex zero based index into feature class for this feature
              * \param featureName name of feature
              * \param featureType type of feature
              * \param location location of feature
              */
            FeatureDescription( const char* const covName, const char* const featClassName, const char* const faccCode,
                const unsigned int featIndex, const char* const featureName, const VPFUtil::FeatureType featureType, const VPFUtil::Coord2DShort& location );

            /** Dtor */
            ~FeatureDescription();

            /** Determine if the feature description is valid
              * \return true if valid else false
              */
            bool IsValid( void ) const { return ( _isValid ); }

            /** Get the name of the coverage that contains this feature
              * \return name of the coverage that contains this feature
              */
            const char* GetCoverageName( void ) const { return ( _covName ); }

            /** Get the name of the feature class that contains this feature
              * \return name of the feature class that contains this feature
              */
            const char* GetFeatureClassName( void ) const { return ( _featClassName ); }

            /** Get the FACC code for feature else "" if feature does not use FACC codes
              * \return FACC code for feature else "" if feature does not use FACC codes
              */
            const char* GetFACCCode( void ) const { return ( _faccCode ); }

            /** Get the zero based index into feature class for this feature
              * \return zero based index into feature class for this feature 
              */
            unsigned int GetFeatureIndex( void ) const { return ( _featIndex ); }

            /** Get the name of the feature
              * \return name of the feature
              */
            const char* GetFeatureName( void ) const { return ( _featureName ); }

            /** Get the type of the feature
              * \return type of the feature
              */
            VPFUtil::FeatureType GetFeatureType( void ) const { return ( _featureType ); }

            /** Get the location of the feature (lon/lat)
              * \return location of the feature (lon/lat)
              */
            VPFUtil::Coord2DShort GetLocation( void ) const { return ( _location ); }

            /** Get the number of attribute pairs in this feature description
              * \return number of attribute pairs in this feature description
              */
            unsigned int GetAttributePairCount( void ) const;

            /** Get an attribute pair from this description
              * \param attribPairNum zero based index to desired attribute pair ( < GetAttributePairCount() )
              * \return desired attribute pair else NULL
              */
            const AttributePair* GetAttributePair( const unsigned int attribPairNum ) const;

            /** add an attribute pair to this description. NOTE: FeatureDescription does not deep copy the attribute pair and owns the 
              *  attribute pair if this method returns success
              * \param attributePair attribute description
              * \return true if success else false 
              */
            bool AddAttributePair( AttributePair* const attributePair );

        protected:
            /** array of attribute pairs */
            typedef VPFUtil::PointerArray<AttributePair> AttributePairArray;

            VPFUtil::WarningBool        _isValid;        /**< true if feature description is valid else false */
            const DNCString             _covName;        /**< name of coverage that contains this feature */
            const DNCString             _featClassName;  /**< name of feature class that contains this feature */
            const DNCString             _faccCode;       /**< FACC code for feature else "" if feature does not use FACC codes */
            const unsigned int          _featIndex;      /**< zero based index into feature class for this feature */
            const DNCString             _featureName;    /**< name of feature */
            const VPFUtil::FeatureType  _featureType;    /**< feature type */
            const VPFUtil::Coord2DShort _location;       /**< location of feature (lon/lat) */
            AttributePairArray          _attributePairs; /**< array of attribute pairs */

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

        /** Ctor
          * \param libNum zero based library index into database for library containing results
          * \param libName name of library that contains results
          */
        QueryResults( const unsigned int libNum, const char* const libName );

        /** Dtor */
        ~QueryResults();

        /** Determine if the results are valid
          * \return true if valid else false
          */
        bool IsValid( void ) const { return ( _isValid ); }

        /** Get the zero based library index into database for library containing results
          * \return zero based library index into database for library containing results
          */
        unsigned int GetLibraryNumber( void ) const { return ( _libNum ); }

        /** Get the name of library that contains results
          * \return name of library that contains results
          */
        const char* GetLibraryName( void ) const { return ( _libName ); }

        /** Get the number of feature descriptions in the results
          * \return number of feature descriptions in the results
          */
        unsigned int GetFeatureDescriptionCount( void ) const;

        /** Get a feature description in the results
          * \param featDescIndex zero based index to desired description ( < GetFeatureDescriptionCount() )
          * \return desired feature description else NULL
          */
        const FeatureDescription* GetFeatureDescription( const unsigned int featDescIndex ) const;

        /** Add the given feature description to the results.  NOTE: QueryResults does not deep copy the description and owns the 
          *  description if this method returns success
          * \param featureDescription description in question
          * \return true if success else false
          */
        bool AddFeatureDescription( FeatureDescription* const featureDescription );

    protected:
        /** array of FeatureDescription pointers */
        typedef VPFUtil::PointerArray<FeatureDescription> FeatureDescriptionArray;

        VPFUtil::WarningBool    _isValid;             /**< true if results are valid else false */
        const unsigned int      _libNum;              /**< zero based library index into database for library containing results */
        const DNCString         _libName;             /**< name of library that contains results */
        FeatureDescriptionArray _featureDescriptions; /**< array of feature descriptions */

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

    /** Tesselate an area using the given tessellator
      * \param tess tessellator to use
      * \param facID face ID corresponding to area to tessellate
      * \param facPrimTable face primitive table containing face corresponding to area to tessellate
      * \param ringTable ring table describing face corresponding to area
      * \param edgPrimTable edge primitive table describing edges corresponding to rings in face
      * \param polyData blind data to be passed to tessellator callbacks else NULL to allow this routine to manage the
      *                 blind data by creating a GLdoubleEdgeArray instance and automatically configuring the tessellator to
      *                 use DNCUtilTessCombine as its tessellator combine function.  If polyData is not NULL, the caller
      *                 must configure the tessellator with its own combine function
      */
    static void TessellateArea( GLUtesselator* tess, const unsigned int facID, const DNCFacePrimTable& facPrimTable,
        const DNCRingTable& ringTable, const DNCEdgePrimTable& edgPrimTable, void* const polyData );
};

/** tessellator combine function
  * \param coords new location of coordinate
  * \param vertex_data vertex data that contributed to the new coord
  * \param weight weights for vertex data
  * \param outData [out] receives newly allocated vertex for new coordinate
  * \param polygon_data blind data handed to gluTessBeginPolygon, will be an instance of
  *         GLdoubleEdgeArray for holding edges for current polygon being tesselated
  */
void CALLBACK DNCUtilTessCombine( GLdouble coords[ 3 ], void* vertex_data[ 4 ], GLfloat weight[ 4 ], void** outData, void* polygon_data );

/** deubg only code for verifying that a triangle is wound CCW 
  * \param tri triangle in question
  * \return true if CCW else false
  */
#if defined( GLS_DEBUG )
static inline bool isCCW( const DNCUtil::Tri& tri )
{
    const VPFUtil::Coord3DLong v = { ( tri.p2.x - tri.p1.x ), ( tri.p2.y - tri.p1.y ), 0.0 };
    const VPFUtil::Coord3DLong w = { ( tri.p3.x - tri.p1.x ), ( tri.p3.y - tri.p1.y ), 0.0 };

    const VPFUtil::Coord3DLong crossProd = { ( v.y * w.z ) - ( v.z * w.y ),
        ( v.z * w.x ) - ( v.x * w.z ),
        ( v.x * w.y ) - ( v.y * w.x ) };

    return ( crossProd.z >= 0 );
}
#endif // _DEBUG

} // end namespace disti

#endif // _DNC_UTIL_H