gls_map_dnc.h

Go to the documentation of this file.

/*! \file
  \brief  The DNCMapChartDataSource class.

  \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 INCLUDED_GLS_MAP_DNC_H
#define INCLUDED_GLS_MAP_DNC_H

#include "dnc_util.h"
#include "gls_cpp_lang_support.h"
#include "gls_map_chart_data_source.h"
#include "vpf_table.h"
#include "vpf_table_header.h"
#include "vpf_util.h"

#define LIB_BASE_NAME "gls_map_dnc"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME

namespace disti
{
// forward ref
class Mutex;
class GlsFontBase;
class DNCDatabase;
class DNCLibrary;
class DNCAsyncCellRenderThread;
class DNCMapChartCell;
#if defined( _WIN32 )
class WGLExtensions;
#else
class GLXExtensions;
#endif // defined( _WIN32 )

/// \defgroup ds_DNC DNC
/// DNC data source

/// Map chart data source for loading Digital Nautical Chart (DNC, MIL-PRF-89023)
/// \ingroup ds_DNC
/// @{
class DNCMapChartDataSource : public GlsMapChartDataSource
{
public:
    /** config library callback for a user supplied library configuration routine
      * \param userData user supplied data for callback (supplied with SetConfigLibCB())
      * \param dncSource DNC data source containing library to configure
      * \param libNum zero based library number of library to configure else -1 for all libraries in source
      */
    typedef void ( *ConfigLibraryCB )( void* const userData, DNCMapChartDataSource& dncSource, const int libNum );

    /**  Draw callback for a user supplied point feature render routine. This routine is called with the model matrix
      * loaded appropriately as to draw at the correct location using the origin. (i.e. a vertex draw to (0,0) will map
      * to the correct location as described by pointCoord. This routine does not need to save the model stack as the
      * caller will push and pop (save) it accordingly. 
      * NOTE: if the point feature in question is configured to use display lists when rendering, then this callback
      *  will be called during the compilation of a display list.  This means that any textures (and mipmaps) used when rendering
      *  the point feature must already be uploaded to GL.
      * \param userData user supplied data for callback (supplied with SetPointFeatureRenderCB())
      * \param dncSource DNC source containing point feature
      * \param libNum zero based library number of library containing point
      * \param covName name (as defined by MIL-PRF-89023) of coverage containing point
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class containing point
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param featIndex zero based index into feature class for point
      * \param featTableHeader table header for point feature table containing point
      * \param featRow row in feature table corresponding to the point feature data for point
      * \param pointCoord location of point feature
      * \param color color assigned to point feature
      * \param region region of the chart that is rendering
      * \param logicalHeight height in logical units corresponding to height of render region       
      */
    typedef void ( *RenderPointFeatureCB )( void* const userData, DNCMapChartDataSource& dncSource, const unsigned int libNum, const char* const covName, const char* const featClassName,
        const unsigned int featIndex, const VPFTableHeader& featTableHeader, const VPFTable::Row& featRow,
        const VPFUtil::Coord2DShort& pointCoord, const glsColor& color,
        const DNCUtil::GeoRegion& region, const double logicalHeight );

    /**  Feature Iterator callback for a user supplied feature configuration routine. 
      * \param userData user supplied data for callback (supplied with IterateFeatures())
      * \param dncSource DNC source containing feature
      * \param libNum zero based library number of library containing feature
      * \param covName name (as defined by MIL-PRF-89023) of coverage containing feature
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class containing feature
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param featType type of feature
      * \param featIndex zero based index into feature class for feature
      * \param featTableHeader table header for feature table containing feature
      * \param featRow row in feature table corresponding to the feature data for the feature
      * \return true if a configuration change was made to a feature else false
      */
    typedef bool ( *FeatureIteratorCB )( void* const userData, DNCMapChartDataSource& dncSource, const unsigned int libNum, const char* const covName, const char* const featClassName,
        const VPFUtil::FeatureType featType, const unsigned int featIndex, const VPFTableHeader& featTableHeader, const VPFTable::Row& featRow );

    /** GL polygon stipple pattern */
    typedef GLubyte GLPolyStipplePattern[ 128u ];

    /** Ctor */
    DNCMapChartDataSource();

    /** Dtor
    * \sa StopRendering
    */
    ~DNCMapChartDataSource();

    /** Stop the rendering thread. This method should be called before
      * any data that may be accessed by the DNC render callbacks is deleted.
      * This is typically called by the destructor of the component that
      * owns this data source.
      * StopRendering should only be called when you are about to delete the
      * data source and it is no longer needed since the data source is
      * not usable after the rendering thread has been killed.
      */
    void StopRendering();

    /** Load a DNC database and initialize the data source.
      * If the database load succeeded, IsValid() will return true.
      * The method should only be called once per DNCMapChartDataSource instance, subsequent calls will have no effect.
      * \param dncRootPath path to dnc root database directory
      */
    void LoadPath( const char* const dncRootPath );

    /** Determine if the data source is valid
      * \pre LoadPath has been called
      * \return true if valid else false
      */
    bool IsValid( void ) const { return ( _isValid ); }

    // See base class
    bool GetAvailableCoverage( GeoRect* dest ) DISTI_METHOD_OVERRIDE;
    // See base class
    unsigned long GetBestLayer( GlsMapView* view, GlsMapChart* chart ) const DISTI_METHOD_OVERRIDE;
    // See base class
    void GetCellList( const GeoRect& coverage, unsigned long layerID, double viewLogicalHeight, double viewGeoHeight, MapChartCellList& viewList ) DISTI_METHOD_OVERRIDE;
    // See base class
    void PostDraw( GlsMapView* view, GlsMapChart* chart ) DISTI_METHOD_OVERRIDE;

    /** Get the number of libraries in the database
      * \return number of libraries in the database else 0
      */
    unsigned int GetLibraryCount( void ) const;

    /** Get the name of the given library
      * \param libNum zero based library number
      * \return name of library else NULL
      */
    const char* GetLibraryName( const unsigned int libNum ) const;

    /** Get the security classification for the given library ( NOTE: library must be loaded to determine security class )
      * \param libNum zero based library number
      * \return security class for library else VPFUtil::SECURITY_CLASS_UNCLASSIFIED if library is not loaded or is invalid
      */
    VPFUtil::SecurityClass GetLibrarySecurityClass( const unsigned int libNum );

    /** Load a library in the database
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param async true to load asynchronously (check IsLibraryLoaded() to see when library is finally loaded)
      * \param preTessellate true to pre-tessellate area features during loading else false to tessellate on demand when rendering
      * \return true if success else false
      */
    bool LoadDNCLibrary( const unsigned int libNum, const bool async, const bool preTessellate );

    /** Determine if a given library is loading asynchronously.  NOTE: call IsLibraryLoaded() to see if loading is complete
      * \param libNum zero based library number for lib in question
      * \return true if loading else false
      */
    bool IsLibraryLoading( const unsigned int libNum ) const;

    /** Determine if a given library is loaded
      * \param libNum zero based library number for lib in question
      * \return true if loading else false
      */
    bool IsLibraryLoaded( const unsigned int libNum );

    /** Unload a library in the database
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param async true to unload asynchronously ( IsLibraryLoaded() will still return false immediately )
      * \return true if success else false
      */
    bool UnloadDNCLibrary( const unsigned int libNum, const bool async );

    /**  Lock and get the given library.  NOTE: Must call UnlockLibrary when done if this routine returns true.
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param lib [out] receives pointer to locked library (NULL if library is not loaded)
      * \return true if library was locked (even if library is not loaded e.g. lib=NULL)
      */
    bool LockLibrary( const unsigned int libNum, DNCLibrary** lib );

    /** Unlock the given library.  Any pointer received from a previous LockLibrary call is now invalid.
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \return true if success else false
      */
    bool UnlockLibrary( const unsigned int libNum );

    /** Show/Hide a library. A library will not be available for tiles if it is hidden
      * \param libNum zero based libray number
      * \param visible true to show else false to hide
      * \return true on success else false
      */
    bool SetLibraryVisible( const unsigned int libNum, const bool visible );

    /**  Notify that a library has had its configuration changed and those changes should be reflected in
      * map cells.  NOTE: This should be called any time a library config change is made in realtime ( i.e. not made
      *  from a config callback )
      * \return true if success else false
      */
    bool NotfiyLibraryConfigChanged( void );

    /** Determine if a library is visible (available for tiles)
      * \param libNum zero based libray number
      * \return true if visible else false
      */
    bool IsLibraryVisible( const unsigned int libNum );

    /** Get the number of map chart cells that are currently completed (rendered) for the given library
      * \param libNum zero based libray number
      * \return number of map chart cells that are currently completed (rendered) for the given library
      */
    unsigned int GetCompletedCellCount( const unsigned int libNum );

    /** Get the geographic extents of a library in the database
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param swCornerLon [out] receives longitude of southwest corner of library on success
      * \param swCornerLat [out] receives latitude of southwest corner of library  on success
      * \param neCornerLon [out] receives longitude of northeast corner of library on success
      * \param neCornerLat [out] receives latitude of northeast corner of library on success
      * \return true if success else false
      */
    bool GetLibraryExtents( const unsigned int libNum, float& swCornerLon, float& swCornerLat, float& neCornerLon, float& neCornerLat ) const;

    /** Test a point against the actual coverage of a given library
      * \param libNum zero based library number
      * \param longitude longitude of point
      * \param latitude latitude of point
      * \return true if in actual library coverage else false
      */
    bool LibraryCoveragePointTest( const unsigned int libNum, const double longitude, const double latitude ) const;

    /** Get the actual coverage area for a library
      * \param libNum zero based library number
      * \param area [out] receives area in degrees (lonxlat) on success
      * \return true on success else false
      */
    bool GetLibraryCoverageArea( const unsigned int libNum, double& area ) const;

    /** Get the scale of the chart in a given library
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param scale [out] reveives the denominator of the chart scale expressed as a fraction (e.g. 80000 --> chart scale of 1/80000)
      * \return true if success else false
      */
    bool GetLibraryScale( const unsigned int libNum, unsigned int& scale );

    /** Query a library in the database about its features
      * \param libNum zero based library number ( < GetLibraryCount() )
      * \param region geographic region to query
      * \param onlyVisibleFeatures true to only return currently visible features else false for all features
      * \return query results else NULL
      */
    const DNCUtil::QueryResults* QueryFeatures( const unsigned int libNum, const DNCUtil::GeoRegion& region, const bool onlyVisibleFeatures );

    /** Show/Hide all coverages and features in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param show true to show else false to hide
      * \return true if success else false
      */
    bool ShowAll( const int libNum, const bool show );

    /** Show/Hide a particular (or all) coverage(s) in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage to show/hide else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param visible true to show else false to hide
      * \return true if at least one coverage show/hide status was set else false
      */
    bool SetCoverageVisible( const int libNum, const char* const covName, const bool visible );

    /** Show/Hide feature(s) in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param visible true to show else false to hide
      * \return true if at least one feature show/hide status was set else false
      */
    bool SetFeatureVisible( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const bool visible );

    /** Set feature(s) color in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param color color
      * \return true if at least one feature color was changed
      */
    bool SetFeatureColor( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const glsColor& color );

    /** Set point feature(s) render callback in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param renderCB render callback else NULL for no callback
      * \param userData user supplied data to be handed to callback
      * \param useMapScale true if point feature should scale with the map (will become larger as the view zooms in),
      *                    false is point feature should scale to attempt maintain the same size in logical space regardless
      *                    of the map zoom
      * \return true if at least one point feature callback was changed
      */
    bool SetPointFeatureRenderCB( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        RenderPointFeatureCB const renderCB, void* const userData,
        const bool useMapScale );

    /** Set feature(s) line stippling in a library ( sets area boundary stipple for area features )
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param stippleFactor (0 if not stippled line) stipple factor (>=1) if line is stippled (see glLineStipple() )
      * \param stipplePattern stipple pattern if line is stippled (see glLineStipple() )
      * \return true if at least one feature line stipple was changed
      */
    bool SetFeatureLineStipple( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const GLint stippleFactor, const GLushort stipplePattern );

    /** Set text feature(s) font in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param font font for text feature
      * \return true if at least one text feature font was changed
      */
    bool SetTextFeatureFont( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        GlsFontBase* const font );

    /** Set area feature(s) polygon stipple pattern in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param polyStipplePattern polygon stipple pattern else NULL to disable polygon stipple 
      * \return true if at least one feature polygon stipple was changed
      */
    bool SetAreaFeaturePolygonStipple( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const GLPolyStipplePattern* const polyStipplePattern );

    /** Show/Hide area feature(s) boundary in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param visible true to show boundary else false to hide
      * \return true if at least one area boundary visibility was changed
      */
    bool SetAreaFeatureBoundaryVisible( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const bool visible );

    /** Set area feature(s) boundary color in a library
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \param color color
      * \return true if at least one area feature boundary color was changed
      */
    bool SetAreaFeatureBoundaryColor( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex,
        const glsColor& color );

    /**  Set the draw order for a feature class in a coverage of a library.  All features behid given draw order will be pushed down the
      * draw order (further back in draw order).
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for feature classes that do
      *                 use FACC codes ( see MIL-PRF-89023 )
      * \param drawOrder zero based desired draw order ( draw Order 0 is the last to draw )
      * \return true if success else false
      */
    bool SetFeatureDrawOrder( const int libNum, const char* const covName, const char* const featClassName, const char* const faccCode,
        const unsigned int drawOrder );

    /** Iterate over features
      * \param featureIteratorCB user supplied callback to be called when iterating
      * \param userData user supplied data to be handed to callback
      * \param libNum zero based library number else -1 for all loaded libraries
      * \param covName name (as defined by MIL-PRF-89023) of coverage else NULL for all coverages.
      *                ( see DNCUtil COVERAGE_NAME constants )
      * \param featClassName name (as defined by MIL-PRF-89023) of feature class else NULL for all features.
      *                          ( see DNCUtil FEATURE_NAME constants )
      * \param faccCode Feature and Attribute Coding Catalog feature code else NULL for all feature codes
      *                 ( see MIL-PRF-89023 )
      * \param intAttribColName additional integer attribute column else NULL to ignore
      * \param intAttribVal integer attribute value to compare against if intAttribColName != NULL
      * \param charAttribColName additional character attribute column else NULL to ignore additional attribute 
      * \param charAttribVal character attribute value to compare against if charAttribColName != NULL
      * \param desFeatIndex zero based feature index for specific feature else -1 for all
      * \return true if at least one feature configuration was changed
      */
    bool IterateFeatures( FeatureIteratorCB const featureIteratorCB, void* const userData, const int libNum, const char* const covName,
        const char* const featClassName, const char* const faccCode,
        const char* const intAttribColName, const unsigned int intAttribVal,
        const char* const charAttribColName, const char* const charAttribVal, const int desFeatIndex );

    /** Set the callback for automatically configuring libraries when loaded
      * \param configLibCB callback else NULL to clear callback
      * \param userData user supplied data to be handed to callback
      * \param reconfigAll true to reconfig all loaded libraries with new callback (if NULL != configLibCB) else false
      */
    void SetConfigLibCB( ConfigLibraryCB const configLibCB, void* const userData, const bool reconfigAll );

    /** Lower/Restore the priority of the async cell render thread
      * \param belowNormal true to set thread priority to below normal else false to set priority to normal
      * \return true if success else false
      */
    bool LowerAsyncCellRenderPriority( const bool belowNormal );

    /** Lower/Restore the priority of the async load threads
      * \param belowNormal true to set thread priority to below normal else false to set priority to normal
      * \return true if success else false
      */
    bool LowerAsyncLoadPriority( const bool belowNormal );

    /** Lower/Restore the priority of the async unload thread
      * \param belowNormal true to set thread priority to below normal else false to set priority to normal
      * \return true if success else false
      */
    bool LowerAsyncUnloadPriority( const bool belowNormal );

protected:
    /** Helper for library loading */
    struct LibrarySlot
    {
        Mutex*      libMutex; /**< mutex for lib pointer */
        DNCLibrary* lib;      /**< DNC library if library is loaded else NULL */
        bool        visible;  /**< true if library is available for tiles else NULL */

        /** Ctor */
        LibrarySlot( void );

        /** Dtor */
        ~LibrarySlot();
    };

    /** array of library slots */
    typedef DynamicArray<LibrarySlot, false> LibraryArray;

    /** array of DNC map cell pointers */
    typedef DynamicArray<DNCMapChartCell*, true> CellPointerArray;

    /** Refresh the given library in the _libPointers array to check for new library load / unloads and autoconfigure libraries as needed
      * \param libNum zero based library number of lib in question
      * \return true if lib pointer changed
      */
    bool RefreshLib( const unsigned int libNum );

    /** Refresh the _libPointers array to check for new library load / unloads and autoconfigure libraries as needed
      */
    void RefreshLibList( void );

    /**  Check for and delete unused cells in the _cellPointers array, pickup any tiles from the render thread.
      */
    void RefreshCellList( void );

    /** Invalidate the textures associated with any cells referencing the given library number.
      * NOTE: It is assumed that the given library is locked with LockLibrary() before calling this routine.
      * \param libNum zero based library number in question
      */
    void InvalidateCells( const unsigned int libNum );

    /**  Populate the given cell list with cells for the given library number and layer that intersect the given view coverage.
      * This routine will create cells as needed and popuplate the _cellPointers arrayfor tiles that need
      * to be created.
      * \param libNum zero based lib number
      * \param libExtents extents of library
      * \param view view coverage
      * \param layer layer number
      * \param viewLogicalHeight The height of the view in logical space
      * \param viewGeoHeight The height of the view in geographic space
      * \param cellList cellList to populate
      */
    void PopulateCells( const unsigned int libNum, const GeoRect& libExtents, const GeoRect& view, const unsigned long layer, double viewLogicalHeight, double viewGeoHeight, MapChartCellList& cellList );

    /** Find a cell in the _cellPointers list that matches the given library number, rect and layer
      * \param libNum zero based library number
      * \param tileRect rect for cell
      * \param tileLogicalHeight The height of the view in logical space
      * \param layer layer number
      * \return matching cell in list else NULL
      */
    DNCMapChartCell* FindCell( const unsigned int libNum, const double tileLogicalHeight, const GeoRect& tileRect, const unsigned long layer );

    /** Get next cell to be rendered. NOTE: returned cell will already have had its ref count increased by one
      * \return next cell to be rendered else NULL if no cell to be rendered
      */
    DNCMapChartCell* GetNextCellToRender( void );

    VPFUtil::WarningBool      _isValid;           /**< true if source is valid else false */
    DNCDatabase*              _dncDb;             /**< DNC database else NULL */
    LibraryArray              _libraries;         /**< LibrarySlots 's for each lib in the database */
    ConfigLibraryCB           _configLibCB;       /**< user supplied library configuration callback else false */
    void*                     _configUserData;    /**< user supplied data for library config callback else NULL */
    Mutex*                    _cellPointersMutex; /**< lock for _cellPointers */
    CellPointerArray          _cellPointers;      /**< array of pointers to map cells */
    DNCAsyncCellRenderThread* _renderThread;      /**< async cell rendering thread else NULL */

    bool _firstTimeLoaded;

#if defined( _WIN32 )
    WGLExtensions* _glEx; /**< Win32 gl extensions else NULL */
#else
    GLXExtensions* _glEx; /**< GLX extensions else NULL */
#endif

    /** static function for routing to GetNextCellToRender(). NOTE: returned cell will already have had its ref count increased by one
      * \param pArguments pointer to DNCMapChartDataSource
      * \return next cell to render else NULL
      */
    static DNCMapChartCell* getNextCellToRender( void* const pArguments );
};
/// @}

} // end namespace disti

#endif // _GLS_MAP_DNC_H