gls_map_shapefile.h

Go to the documentation of this file.

/*! \file
\brief  The shapefile data source for GlsMapToolkit.

\par Copyright Information

    Copyright (c) 2016 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_SHAPEFILE_H
#define INCLUDED_GLS_MAP_SHAPEFILE_H
#include "gls_include.h"
#include "gls_map_chart_data_source.h"
#include "scoped_ptr.h"
#include "shapefile_util.h"

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

// Also auto-lib the third-party library GDAL
#undef GLS_LIB_TYPE
#undef GLS_LIB_CRT_SUFFIX
#undef GLS_AUTOLIB_SUFFIX
#define GLS_AUTOLIB_SUFFIX
#define GLS_LIB_TYPE
#define GLS_LIB_CRT_SUFFIX
#define LIB_BASE_NAME "gdal"
#include "gls_auto_lib.h"
#undef LIB_BASE_NAME
#undef GLS_LIB_TYPE
#undef GLS_LIB_CRT_SUFFIX
#undef GLS_AUTOLIB_SUFFIX

namespace disti
{
class GlsFontBase;
/// \defgroup ds_Shapefile Shapefile
/// Shapefile data source

///////////////////////////////////////////////////////////////////////////////////////////////////
/// \brief Map chart data source for loading Shapefiles
///
/// \note The ESRI Shapefile specification does not deal with shapefiles at different scales or
///       levels of detail (e.g., 1:100k, 1:250k, 1:1M, etc.). This program, paralleling the DNC
///       map data source, calls these different shapefiles "libraries". Multiple libraries can
///       be loaded simultaneously and then unloaded when desired, all in the same data source.
///
/// \note The ESRI Shapefile specification calls sets of features "layers", but the MapToolkit
///       already used that term to refer to the different bin sizes it renders the Shapefile's
///       vector data at. Due to existing virtual function names with "layer" in them, we retain
///       MapToolkit's use of the term and substitute "feature set" (or use "Shapefile layer"
///       when necessary) for Shapfile's notion of a "layer".
///
///       A feature set often (but not always) comes from a single .shp file with a single
///       Shapefile layer and contains different subtypes of features (e.g., natural.shp may have
///       feature types "forest", "river", etc.).
///
/// \note Each library has a set of attributes (visibility, color, etc.) for each of
///       its feature sets, and each feature set has optional attributes to override the defaults
///       for a specific feature type within set. These default and overridden attributes can be
///       controlled with the setter and getter member functions.
///
///       For instance, the "natural" feature set could have black as the line color for all its
///       features but override it to blue for rivers and green for forests.
///
/// \ingroup ds_Shapefile
/// @{
///////////////////////////////////////////////////////////////////////////////////////////////////
class ShapefileMapChartDataSource : public GlsMapChartDataSource
{
public:
    typedef Shapefile::LibraryID LibraryID; // For easier reading
    typedef Shapefile::LayerID   LayerID;

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// 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.
    /// \param userData user supplied data for callback (supplied with SetPointFeatureRenderCB())
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    /// \param featureType The name of a type of feature within the feature set (e.g., in a
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    /// \param longitude longitude of point feature
    /// \param latitude longitude 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,
        const char*     featureSet,
        const char*     featureType,
        double          longitude,
        double          latitude,
        const glsColor& color,
        const GeoRect&  region,
        const double    logicalHeight );

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Cartesian coordinate used by the points that define the paths loaded from shapefiles
    struct ShapePoint
    {
        ShapePoint()
            : x( 0.0f )
            , y( 0.0f )
        {
        }

        ShapePoint( float x_, float y_ )
            : x( x_ )
            , y( y_ )
        {
        }

        float x; ///< \param x horizontal component of the point
        float y; ///< \param y vertical component of the point
    };

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Draw callback for a user supplied line feature render routine. This routine is called with the
    /// model matrix loaded appropriately as to draw at the correct location.
    /// \param userData user supplied data for callback (supplied with SetPointFeatureRenderCB())
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    /// \param featureType The name of a type of feature within the feature set (e.g., in a
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    /// \param points the vertices of the path.
    /// \param region region of the chart that is rendering
    /// \param logicalHeight height in logical units corresponding to height of render region
    typedef void ( *RenderLineFeatureCB )(
        void* const                     userData,
        const char*                     featureSet,
        const char*                     featureType,
        const DynamicArray<ShapePoint>& points,
        const GeoRect&                  region,
        const double                    logicalHeight );

    /// Constructor
    ShapefileMapChartDataSource();

    /// Destructor - stops rendering and releases all libraries.
    ~ShapefileMapChartDataSource();

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Load a Shapefile (or files) from the given path and associate it with a given library identifier.
    ///
    /// \param shapefileRootPath path to Shapefile or directory containing Shapefile(s). Multiple files
    ///        in one folder will be considered one library. If null, empty, or not found, the function
    ///        emits an error and returns false.
    ///
    /// \param libraryID The library ID (see note), often the scale of this library. It acts as a
    ///        handle to this library for other operations on it using this data source.
    ///
    ///        If the path loads successfully but the ID has already been used, it will unload the old
    ///        data and replace it with the data from this path after emitting a warning to the console
    ///        (unload first to avoid the warning).
    ///
    ///        The library ID also controls what order multiple enabled libraries are rendered in,
    ///        starting with the lowest libraryID and going to the largest.
    ///
    /// \note This method can be called repeatedly to add multiple libraries to this data source.
    ///       The loading of different libraries can take place in any order, and multiple libraries
    ///       can be loaded into the same data source object. Only the first library loaded is
    ///       enabled for rendering; EnableLibraryRendering() controls which library or libraries
    ///       render. The libraryID controls the order of rendering when multiple libraries are enabled.
    ///
    /// \sa UnloadLibrary()
    /// \sa GetLoadedLibraries()
    /// \sa EnableLibraryRendering()
    /// \note We would name this LoadLibrary(), but Windows \#defines LoadLibrary, which interferes.
    /// \return Returns whether the path was loaded successfully.
    bool LoadLibraryAs( const char* shapefileRootPath, LibraryID libraryID );

    /// Unloads a given library.
    /// \return true if the library was found.
    /// \sa LoadLibraryAs()
    /// \sa GetLoadedLibraries()
    bool UnloadLibrary( LibraryID libraryID );

    /// Returns a list of all currently loaded library IDs.
    /// \sa LoadLibraryAs()
    /// \sa UnloadLibrary()
    DynamicArray<LibraryID> GetLoadedLibraries() const;

    ///////////////////////////////////////////////////////////////////////////////////////////////////
    /// Enable a given library to render. By default, only one library is set to render at a time.
    /// This function allows the user to render multiple libraries at a time, which may be useful
    /// if the libraries have orthogonal features in them, e.g., one library for roads, one for
    /// buildings, etc. (More commonly, a library has multiple feature sets within it, and each
    /// library covers the same geographic area but represents a different scale or level of detail.)
    /// Libraries are rendered in the order of their LibraryIDs, starting with the smallest value
    /// on the "bottom" of the texture and the next smallest writing on top of it (possibly overwriting).
    ///
    /// \param libraryID The library to update. If not found, this function emits a warning to
    ///        the console and returns false without changing rendering.
    /// \param enable Whether the library should be enabled (defaults to true).
    /// \return true if the library was found.
    /// \sa IsLibraryRenderingEnabled()
    /// \sa LoadLibraryAs()
    bool EnableLibraryRendering( LibraryID libraryID, bool enable = true );

    /// Query whether a given library is set to render.
    /// \param libraryID The library to update. If not found, this function emits a warning to
    ///        the console and returns false without changing the output parameter.
    /// \param[out] isEnabled Whether the library is enabled
    /// \return true if the library was found.
    /// \sa EnableLibraryRendering()
    bool IsLibraryRenderingEnabled( LibraryID libraryID, bool& isEnabled ) const;

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Returns a list of feature set names in the order they are to be drawn, from bottom to top.
    /// \param libraryID The library to query. If not found, the function emits a warning to the console
    ///                  and returns an empty array.
    /// \note The caller is NOT responsible to delete the pointers in the array. They are guaranteed
    ///       valid until LoadLibraryAs() or UnloadLibrary() is called for this \a libraryID.
    /// \sa SetOrderedFeatureSetNames()
    /// \sa GetFeatureNames()
    DynamicArray<const char*> GetOrderedFeatureSetNames( LibraryID libraryID ) const;

    /// Sets the feature set names in the order they are to be drawn.
    /// \param libraryID The library to update.
    /// \param orderedFeatureSetNames The list of names in order from bottom to top. If any feature
    ///                               set name is null, empty, or does not exist or if a name is
    ///                               missing from the list, a warning is emitted to the console,
    ///                               and the function returns false without changing draw order.
    /// \note Use GetOrderedFeatureSetNames() to get a valid list of feature set names, reorder them
    ///        in place, and pass the result into this function.
    /// \note This function does NOT take ownership of the strings in the array, though it may already
    ///       have ownership if the array is a reordering of the result of GetOrderedFeatureSetNames().
    /// \return true if all names were applied.
    bool SetOrderedFeatureSetNames( LibraryID libraryID, const DynamicArray<const char*>& orderedFeatureSetNames );

    /// Returns a list of feature types in the given \a featureSetName within the given library.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null or not found, this function
    ///                   emits an error to the console and returns an empty array.
    /// \note The caller is NOT responsible to delete/free the pointers in the returned array. They are
    ///       guaranteed valid until LoadLibraryAs() or UnloadLibrary() is called for this library.
    DynamicArray<const char*> GetFeatureTypes( LibraryID libraryID, const char* featureSet ) const;

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current visibility of the features in the given feature set, optionally limited to a single feature type.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file). If null,
    ///        empty, or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in a
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default visibility for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] isVisible Whether the requested features are visible.
    /// \return true if the feature set and type (if not null/empty) were found. If false, the
    ///         output parameter is unchanged.
    bool GetFeatureSetVisibility( LibraryID libraryID, const char* featureSet, const char* featureType, bool& isVisible ) const;

    /// Sets the visibility for features in a feature set.
    /// \param libraryID The library to update.
    /// \param featureSet The name of the feature set. If null, sets the visibility for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false without changing visibility.
    /// \param featureType The type of feature within the feature set. If null or empty, it applies
    ///                    to the default feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param isVisible The visibility to be applied.
    /// \note This can be called multiple times, once with \a featureType == NULL to set the default
    ///       and then with \a featureType != NULL to change specific features.
    /// \return true if the feature set and was found.
    bool SetFeatureSetVisibility( LibraryID libraryID, const char* featureSet, const char* featureType, bool isVisible );

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current point style of the features in feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    ///                   If null or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in the
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default point style for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] color The point color for the requested features.
    /// \param[out] renderCB render callback else NULL for no callback
    /// \param[out] userData user supplied data to be handed to callback
    /// \param[out] 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 the feature set and type (if not null/empty) were found. If false, the
    ///         output parameters are unchanged.
    bool GetFeatureSetPointStyle(
        LibraryID   libraryID,
        const char* featureSet,
        const char* featureType,
        // Output params:
        glsColor&             color,
        RenderPointFeatureCB& renderCB,
        void*&                userData,
        bool&                 useMapScale ) const;

    /// Sets the point style (outline for polygon features) for features in a set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null, sets the style for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false
    /// \param featureType The name of the feature. If null or empty, it applies to the default
    ///                    attributes for the feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param color The RGBA color value for points
    /// \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
    /// \note This can be called multiple times, once with \a featureType == NULL to set the default
    ///       and then with \a featureType != NULL to change specific features.
    /// \return true if the feature set was found.
    bool SetFeatureSetPointStyle(
        LibraryID                  libraryID,
        const char*                featureSet,
        const char*                featureType,
        const glsColor&            color,
        const RenderPointFeatureCB renderCB    = NULL,
        void* const                userData    = NULL,
        const bool                 useMapScale = NULL );

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current line style of the features in feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    ///                   If null or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in the
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default line style for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] color The line color for the requested features.
    /// \param[out] width The line width for the requested features.
    /// \param[out] stipplePattern    The line stipple pattern for the requested features.
    /// \param[out] stippleMultiplier The line stipple multiplier for the requested features.
    /// \return true if the feature set and type were found and they were set with the
    ///         corresponding overload of SetFeatureSetLineStyle(); false otherwise.
    ///         (If returning false, the output parameters are unchanged.)
    bool GetFeatureSetLineStyle(
        LibraryID   libraryID,
        const char* featureSet,
        const char* featureType,
        // Output params:
        glsColor& color,
        float&    width,
        uint16_t& stipplePattern,
        int&      stippleMultiplier ) const;

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current line callback for the feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    ///                   If null or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in the
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default line style for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] renderCB    The line callback
    /// \param[out] userData The user data passed to the callback
    /// \return true if the feature set and type were found and they were set with the
    ///         corresponding overload of SetFeatureSetLineStyle(); false otherwise.
    ///         (If returning false, the output parameters are unchanged.)
    bool GetFeatureSetLineStyle(
        const LibraryID   libraryID,
        const char* const featureSet,
        const char* const featureType,
        // Output params:
        RenderLineFeatureCB& renderCB,
        void*&               userData ) const;

    /// Sets the line style (outline for polygon features) for features in a set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null, sets the style for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false
    /// \param featureType The name of the feature. If null or empty, it applies to the default
    ///                    attributes for the feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param color The RGBA color value for lines
    /// \param width The line width
    /// \param stipplePattern The stipple pattern for lines (see documentation of glLineStipple())
    /// \param stippleMultiplier The multiplier for stippling (see documentation of glLineStipple())
    /// \note There are two overloads of this function -- this one that supplies OpenGL line settings
    ///       and another that supplies a user callback for custom drawing. Calling this function with
    ///       the same \a libraryID, \a featureSet, and \a featureType as a previously configured with
    ///       a callback will discard the callback.
    /// \return true if the feature set was found.
    bool SetFeatureSetLineStyle(
        LibraryID   libraryID,
        const char* featureSet,
        const char* featureType,
        glsColor    color,
        float       width             = DEF_LINE_WIDTH,
        uint16_t    stipplePattern    = DEF_LINE_STIPPLE_PATTERN,
        int         stippleMultiplier = 0 /* disabled */ );

    /// Sets the line callback for features in a set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null, sets the style for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false
    /// \param featureType The name of the feature. If null or empty, it applies to the default
    ///                    attributes for the feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param renderCB the line callback
    /// \param userData The optional user data passed to the callback, can be NULL if unused.
    /// \note There are two overloads of this function -- this one that supplies OpenGL line settings
    ///       and another that supplies a user callback for custom drawing. Calling this function with
    ///       the same \a libraryID, \a featureSet, and \a featureType as a previously configured with
    ///       OpenGL line settings will discard the OpenGL line settings.
    /// \return true if the feature set was found. Will return false and have no effect if renderCB is NULL.
    bool SetFeatureSetLineStyle(
        LibraryID                 libraryID,
        const char*               featureSet,
        const char*               featureType,
        const RenderLineFeatureCB renderCB,
        void* const               userData = NULL );

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current fill style of the features in feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    ///                   If null or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in the
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default visibility for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] color The fill color for the requested features.
    /// \param[out] drawBoundary Whether or not to draw the area boundary
    /// \param[out] boundaryColor The boundary color for the requested features.
    /// \param[out] boundaryWidth The line width
    /// \param[out] boundaryStipplePattern The stipple pattern for lines (see documentation of glLineStipple())
    /// \param[out] boundaryStippleMultiplier The multiplier for stippling (see documentation of glLineStipple())
    /// \return true if the feature set and type (if not null/empty) were found. If false, the
    ///         output parameter is unchanged.
    bool GetFeatureSetFillStyle( LibraryID libraryID,
        const char*                        featureSet,
        const char*                        featureType,
        // Output params:
        glsColor& color,
        bool&     drawBoundary,
        glsColor& boundaryColor,
        float&    boundaryWidth,
        uint16_t& boundaryStipplePattern,
        int&      boundaryStippleMultiplier ) const;

    /// Sets the fill style for polygon features in the feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null, sets the style for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false
    /// \param featureType The name of the feature. If null or empty, it applies to the default
    ///                    attributes for the feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param color The RGBA color value for filling polygons.
    /// \param boundaryColor The boundary color for the requested features.
    /// \param drawBoundary Whether or not to draw the area boundary
    /// \param boundaryWidth The line width
    /// \param boundaryStipplePattern The stipple pattern for lines (see documentation of glLineStipple())
    /// \param boundaryStippleMultiplier The multiplier for stippling (see documentation of glLineStipple())
    /// \note This can be called multiple times, once with \a featureType == NULL to set the default
    ///       and then with \a featureType != NULL to change specific features.
    /// \return true if the feature set was found.
    bool SetFeatureSetFillStyle(
        LibraryID       libraryID,
        const char*     featureSet,
        const char*     featureType,
        const glsColor& color,
        bool            drawBoundary              = false,
        const glsColor& boundaryColor             = glsColor( 0, 0, 0, 255 ),
        float           boundaryWidth             = DEF_LINE_WIDTH,
        uint16_t        boundaryStipplePattern    = DEF_LINE_STIPPLE_PATTERN,
        int             boundaryStippleMultiplier = 0 /* disabled */ );

    /////////////////////////////////////////////////////////////////////////////////////////////////////
    /// Retrieves the current text style of the features in feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set (often corresponds to a single .shp file).
    ///                   If null or not found, it emits a warning to the console and returns false.
    /// \param featureType The name of a type of feature within the feature set (e.g., in the
    ///                    "natural" feature set, there might be "water" and "forest" among others).
    ///                    If null or empty, it returns the default visibility for the feature set.
    ///                    If not found, it emits a warning to the console and returns false.
    /// \param[out] glsFont The instance of a font in this GL Studio project
    /// \param[out] textColor The text color for the requested features.
    /// \param[out] isVisible Whether the text is visible for the requested features.
    /// \param[out] scale The scale of the text (default = 1.0)
    /// \param[out] xOffset horizontal offset from the default text location (text starts at the center of its objects extents)
    /// \param[out] yOffset vertical offset from the default text location (text starts at the center of its objects extents)
    /// \note This function does not take ownership of the strings passed in.
    /// \return true if the feature set and type (if not null/empty) were found. If false, the
    ///         output parameters are unchanged.
    bool GetFeatureSetTextStyle(
        LibraryID   libraryID,
        const char* featureSet,
        const char* featureType,
        // Output params:
        GlsFontBase*& glsFont,
        glsColor&     textColor,
        double&       scale,
        double&       xOffset,
        double&       yOffset,
        bool&         isVisible ) const;

    /// Sets the text style for a feature set.
    /// \param libraryID The library to query.
    /// \param featureSet The name of the feature set. If null, sets the style for all features sets.
    ///                   If non-null and not found, this function emits a warning to the console and
    ///                   returns false
    /// \param featureType The name of the feature. If null or empty, it applies to the default
    ///                    attributes for the feature set. If not found, it creates a new feature attribute
    ///                    override entry.
    /// \param glsFont The instance of a font in this GL Studio project
    /// \param textColor Color of the text. (Defaults to black.)
    /// \param isVisible Whether the text is visible for the requested features.
    /// \param scale The scale of the text (default = 1.0)
    /// \param xOffset horizontal offset from the default text location (text starts at the center of its objects extents)
    /// \param yOffset vertical offset from the default text location (text starts at the center of its objects extents)
    /// \note This can be called multiple times, once with \a featureType == NULL to set the default
    ///       and then with \a featureType != NULL to change specific features.
    /// \note This function does not take ownership of the strings passed in.
    /// \return true if the feature set was found.
    bool SetFeatureSetTextStyle(
        LibraryID       libraryID,
        const char*     featureSet,
        const char*     featureType,
        GlsFontBase*    glsFont,
        const glsColor& textColor = glsColor( 0, 0, 0, 255 ),
        double          scale     = 1.0,
        double          xOffset   = 0.0f,
        double          yOffset   = 0.0f,
        bool            isVisible = true );

    ///////////////////////////////////////////////////////////////////////////////////////////////
    /// Sets the geographical size of the region to cache. Each library has its own cache region.
    /// \param libraryID The library whose cache size to adjust.
    /// \param degreesLongitude the width of cache size in degrees of longitude
    /// \param degreesLatitude the height of cache size in degrees of latitude
    /// \return true if the library was found.
    bool SetCacheDimensions( LibraryID libraryID, double degreesLongitude, double degreesLatitude );

    ///////////////////////////////////////////////////////////////////////////////////////////////
    // Thread priority control
    ///////////////////////////////////////////////////////////////////////////////////////////////
    bool LowerAsyncCellRenderPriority( bool belowNormal );

    ///////////////////////////////////////////////////////////////////////////////////////////////
    // Implement base class interface
    ///////////////////////////////////////////////////////////////////////////////////////////////
    /// See base class
    bool GetAvailableCoverage( GeoRect* dest ) DISTI_METHOD_OVERRIDE;

    /// See base class
    /// \note: "Layer" here refers to internal resolution level, not Shapefile layer.
    LayerID GetBestLayer( GlsMapView* view, GlsMapChart* chart ) const DISTI_METHOD_OVERRIDE;

    /// See base class
    void GetCellList( const GeoRect& coverage, LayerID layerID, double viewLogicalHeight, double viewGeoHeight, MapChartCellList& viewList ) DISTI_METHOD_OVERRIDE;
    ///////////////////////////////////////////////////////////////////////////////////////////////

    /// Attorney-client idiom for exposing rendering details only to those classes that need it.
    /// \note For internal use only.
    class RenderingAttorney
    {
        // Client list
        friend class ShapefileMapChartCell;

        // Services
        static Shapefile::ScopedLibraryRendererHolder GetLibraryRenderer( const ShapefileMapChartDataSource&, LibraryID );
    };

private:
    ///////////////////////////////////////////////////////////////////////////////////////////////
    // Pimpl idiom
    ///////////////////////////////////////////////////////////////////////////////////////////////
    class ShapefileMapChartDataSourceImpl;
    ScopedPtr<ShapefileMapChartDataSourceImpl> _impl;

    // Disable copying and moving
    ShapefileMapChartDataSource( const ShapefileMapChartDataSource& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const ShapefileMapChartDataSource& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
/// @}
} // end namespace disti

#endif // INCLUDED_GLS_MAP_SHAPEFILE_H