gls_map_dted.h

Go to the documentation of this file.

/*! \file
  \brief  The DTEDMapChartDataSource class header

  \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_DTED_H
#define INCLUDED_GLS_MAP_DTED_H

#include "gls_color.h"
#include <string>

#include "gls_map_chart_data_source.h"

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

// The 'null' value for elevation data; this denotes an invalid or missing data point in the dted
// file.
#define DTED_NULL_ELEVATION_VALUE -32767

namespace disti
{
class DTEDElevationDataStore;
class DTEDMapChartCellManager;
class DTEDFileLoadThread;
class DTEDCalcParamsStore;
class DTEDWorkerThreadManager;
class DTEDShaderManager;

/// \defgroup ds_DTED DTED
/// DTED data source

/** Runtime implementation of a DTEDMapChartDataSource 
  * \ingroup ds_DTED
  * @{
  */
class DTEDMapChartDataSource : public GlsMapChartDataSource
{
public:
    /** Constructor */
    DTEDMapChartDataSource();
    /** Destructor */
    virtual ~DTEDMapChartDataSource();

    // GlsMapChartDataSource inherited methods

    /** \sa GlsMapChartDataSource */
    virtual bool GetAvailableCoverage( GeoRect* dest ) DISTI_METHOD_OVERRIDE;
    /** \sa GlsMapChartDataSource */
    void GetCellList( const GeoRect& coverage, unsigned long layerID, double viewLogicalHeight, double viewGeoHeight, MapChartCellList& viewList ) DISTI_METHOD_OVERRIDE;
    /** \sa GlsMapChartDataSource */
    virtual bool AreAllCellsLoaded( GlsMapView* view, GlsMapChart* chart ) DISTI_METHOD_OVERRIDE;

    // Source data file specification

    /**
      * Reads in a single DTED file and adds its data to the data source.
      * \param filename  The path and name of the file to be read in
      */
    void AddDataFile( const std::string& filename );

    /**
      * Reads in all compatble DTED files within the specified directory and adds their data to
      * the data source.
      * \param directory  The path of the directory containing the files to be read in
      * \param recurse  true if the file search should decend into child directories, false
      *                 otherwise
      */
    void AddAllFiles( const std::string& directory, bool recurse );

    // Utility functions

    /**
      * Retrieves one data point from the currently loaded data.
      * Performs interpolation if the requested location is between data points.
      * \param latDegs  The latitude of the height data point to retrieve, in degrees
      * \param lonDegs  The longitude of the height data point to retrieve, in degrees
      * \return  The terrain height at the specified location, or DTED_NULL_ELEVATION_VALUE if
      *          no data is available for that location.
      */
    short GetElevationDataPoint( double latDegs, double lonDegs );

    /**
      * Retrieves one data point from the currently loaded data.
      * Performs interpolation if the requested location is between data points.
      * \param coord  The GeoCoord structure containing the location of the data point
      * \return  The terrain height at the specified location, or DTED_NULL_ELEVATION_VALUE if
      *          no data is available for that location.
      */
    short GetElevationDataPoint( GeoCoord coord );

    // Special configuration

    /**
      * Sets the current height of the aircraft for use in the elevation banding and threat
      * region rendering. This value is measured in meters above sea level. Negative height
      * values represent elevations below sea level.
      * \param aircraftHeight  The current height of the aircraft
      */
    void SetAircraftHeight( short aircraftHeight );

    // Diffuse Terrain layer configuration

    /** Enables or disables rendering of the diffuse shaded terrain.
      * \param enabled  true if terrain should be rendered shaded, false if it should not
      */
    void SetDiffuseTerrainLayerEnabled( bool enabled );

    /** Sets the direction of the light (not position) used in the diffuse terrain layer.
      * \param x  The X value of the direction vector.
      * \param y  The Y value of the direction vector.
      * \param z  The Z value of the direction vector.
      */
    void SetDiffuseTerrainLayerLightDirection( float x, float y, float z );

    /**
      * Sets the transparency for the diffuse terrain.
      * \param alpha  The terrain's alpha color component. 0-255 range.
      */
    void SetDiffuseTerrainLayerTransparency( unsigned char alpha );

    // Height Terrain layer configuration

    /**
      * Enables or disables rendering of the height terrain.
      * \param enabled  true if terrain should be rendered, false if it should not
      */
    void SetTerrainLayerEnabled( bool enabled );

    /**
      * Sets the intensity range for the terrain. The brightness of the terrain pixels will
      * always be within this range. Mapping of terrain elevation values to grayscale
      * intensity values is performed using linear interpolation, with the low and high
      * elevation values mapped to the low and high intensity values, respectively.
      * \param lowValue  The lowest intensity value used to render the terrain. Must be at
      *                  least 1.
      * \param highValue  The highest intensity value used to render the terrain. Must be
      *                   greater than or equal to the low value.
      */
    void SetTerrainLayerIntensityRange( unsigned char lowValue, unsigned char highValue );

    /**
      * Sets the elevation range for the terrain. Elevation values outside of this range are
      * clamped to the nearest value within the range. Mapping of terrain elevation values to
      * grayscale intensity values is performed using linear interpolation, with the low and
      * high elevation values mapped to the low and high intensity values, respectively.
      * \param lowValue  The elevation lower limit value.
      * \param highValue  The elevation upper limit value. Must be greater than or equal to the
      *                   low value.
      */
    void SetTerrainLayerElevationRange( short lowValue, short highValue );

    /**
      * Sets the transparency for the height terrain.
      * \param alpha  The terrain's alpha color component. 0-255 range.
      */
    void SetTerrainLayerTransparency( unsigned char alpha );

    /**
      * Enables or disables water rendering mode. If enabled, all elevation values at or below
      * sea level (elevation zero) are considered to be 'water', and are rendered using the
      * water color.
      * \param enabled  true if water mode should be enabled, false if disabled
      */
    void SetTerrainLayerWaterEnabled( bool enabled );

    /**
      * Sets the color of the water for water rendering mode. If water rendering mode is
      * enabled, all elevation values at or below sea level (elevation zero) are considered to
      * be 'water' and are rendered using this color. This is set for both height and diffuse terrain.
      * \param waterColor  The color to use for rendering water
      */
    void SetTerrainLayerWaterColor( const glsColor& waterColor );

    // Terrain Elevation Banding configuration

    /**
      * Enables or disables rendering of the Terrain Elevation Banding.
      * \param enabled  true if banding should be rendered, false if it should not
      */
    void SetBandingLayerEnabled( bool enabled );

    /**
      * Sets the number of bands to use in the elevation banding rendering.
      * \param numberOfBands  The number of elevation bands. Must be in the range 1 - 16,
      *                       inclusive.
      */
    void SetBandingLayerBandCount( unsigned int numberOfBands );

    /**
      * Sets the render color of one of the terrain elevation bands.
      * \param bandIndex  The zero-based index of the band to set the color of. Must be in the
      *                   range 0 - 15.
      * \param bandColor  The color to use when rendering the specified elevation band.
      */
    void SetBandingLayerBandColor( unsigned int bandIndex, const glsColor& bandColor );

    /**
      * Sets the 'distance' for one of the terrain elevation bands. This value represents the
      * number of meters between the low and high boundaries for the elevation band. (Or, in
      * the case of the top elevation band, the number of meters between the bottom of the band
      * and the aircraft height.)
      * \param bandIndex  The zero-based index of the band to set the distance of. Must be in
      *                   the range 0 - 15.
      * \param bandDistance  The band's distance value, measured in meters.
      */
    void SetBandingLayerBandDistance( unsigned int bandIndex, unsigned short bandDistance );

    // Elevation Contour Lines configuration

    /**
      * Enables or disables rendering of the Terrain Contour Lines.
      * \param enabled  true if contour lines should be rendered, false if they should not
      */
    void SetContourLayerEnabled( bool enabled );

    /**
      * Sets the draw priority of the contour lines. If this value is set to true, the contour
      * lines are drawn on top of all other map elements. If false, the contour lines are drawn
      * on top of the terrain but underneath the elevation banding and threat regions.
      * \param drawOnTop  true to draw contour lines on top, false otherwise
      */
    void SetContourLayerDrawPriority( bool drawOnTop );

    /**
      * Sets the elevation interval for the contour lines, in meters. A contour line is
      * rendered wherever the terrain elevation crosses any integer multiple of this value.
      * \param interval  The interval distance, in meters. Must be at least 1.
      */
    void SetContourLayerInterval( unsigned short interval );

    /**
      * Sets the render color for the contour lines.
      * \param lineColor  The color to use when rendering contour lines
      */
    void SetContourLayerLineColor( const glsColor& lineColor );

    /**
      * Sets the thickness of the rendered contour lines, in pixels.
      * \param lineThickness  The contour line thickness in pixels
      */
    void SetContourLayerLineThickness( unsigned char lineThickness );

    /**
      * Sets the 'quality' of the contour lines. If this value is false, contour lines are only
      * drawn at elevation data point boundaries. If this value is true, bilinear interpolation
      * is used to calculate contour lines within the elevation point boundaries.
      * \param highQuality  true to use interpolation for contour lines, false otherwise
      */
    void SetContourLayerHighQuality( bool highQuality );

    // Threat Region configuration

    /**
      * Enables or disables rendering of the Threat Intervisibility regions.
      * \param enabled  true if threat regions should be rendered, false if they should not
      */
    void SetThreatLayerEnabled( bool enabled );

    /**
      * Sets the elevation band priority for the threat regions. This value indicates which
      * terrain elevation bands that the threat regions should take render priority over. Any
      * elevation bands with an index equal to or higher than this value are visually
      * superseded by the presense of a threat region. For example, if this value is 2, then
      * the first two elevation bands are always displayed, even within threatened regions, but
      * the threat regions are displayed instead of the third (and subsequent) bands.
      * \param bandIndex  The index of the elevation band which the threat region should
      *                   visually override. Must be in the range 0 - 15, inclusive.
      */
    void SetThreatLayerBand( unsigned int bandIndex );

    /**
      * Enables or disables one of the threat sources for the threat region rendering. A
      * disabled threat never generates any threat region.
      * \param threatIndex  The zero-based index of the threat to enable or disable. Must be in
      *                     the range 0 - 15, inclusive.
      * \param enabled  true to enable the threat, false to disable it
      */
    void SetThreatLayerThreatEnabled( unsigned int threatIndex, bool enabled );

    /**
      * Sets the position of a threat source. The location structure contains the latitude
      * (degrees), longitude (degrees), and altitude (meters) of the threat.
      * \param threatIndex  The zero-based index of the threat to set the location of. Must be
      *                     in the range 0 - 15, inclusive.
      * \param location  The structure containing the threat's new location.
      */
    void SetThreatLayerThreatLocation( unsigned int threatIndex, GeoCoord location );

    /**
      * Sets the radius of a threat's 'Algorithm' area. Locations outside of this range are not
      * considered in the line-of-sight calculations.
      * \param threatIndex  The zero-based index of the threat to set the range of. Must be in
      *                     the range 0 - 15, inclusive.
      * \param sightRadius  The distance at which this source can threaten, measured in meters.
      */
    void SetThreatLayerThreatRadius( unsigned int threatIndex, double sightRadius );

    /**
      * Sets the radius of a threat's 'Lethality' area. A circle of this radius is drawn
      * centered on the threat's location.
      * \param threatIndex  The zero-based index of the threat to set the range of. Must be in
      *                     the range 0 - 15, inclusive.
      * \param lethalityRadius  The radius of the lethality circle, measured in meters.
      */
    void SetThreatLayerThreatLethalityRadius( unsigned int threatIndex, double lethalityRadius );

    /**
      * Sets the radius of a threat's 'Detection' area. A circle of this radius is drawn
      * centered on the threat's location.
      * \param threatIndex  The zero-based index of the threat to set the range of. Must be in
      *                     the range 0 - 15, inclusive.
      * \param detectionRadius  The radius of the detection circle, measured in meters.
      */
    void SetThreatLayerThreatDetectionRadius( unsigned int threatIndex, double detectionRadius );

    /**
      * Sets a threat's height. This value is added to the threat's altitude to determine it's
      * elevation for the threat intervisibility calculation.
      * \param threatIndex  The zero-based index of the threat to set the height of. Must be in
      *                     the range 0 - 15, inclusive.
      * \param height  The height of the threat, in meters.
      */
    void SetThreatLayerThreatHeight( unsigned int threatIndex, double height );

    /**
      * Sets the render color of the threat regions.
      * \param threatColor  The color to use when rendering the threat regions
      */
    void SetThreatLayerColor( const glsColor& threatColor );

    /**
      * Enables or disables rendering of the 'Algorithm' threat ring.
      * \param enabled  true to enable the ring, false to disable it
      */
    void SetThreatLayerAlgorithmRingEnabled( bool enabled );

    /**
      * Enables or disables rendering of the 'Lethality' threat ring.
      * \param enabled  true to enable the ring, false to disable it
      */
    void SetThreatLayerLethalityRingEnabled( bool enabled );

    /**
      * Enables or disables rendering of the 'Detection' threat ring.
      * \param enabled  true to enable the ring, false to disable it
      */
    void SetThreatLayerDetectionRingEnabled( bool enabled );

    /**
      * Enables or disables rendering of dashes on the 'Algorithm' threat ring.
      * \param enabled  true to enable dashes, false to disable them
      */
    void SetThreatLayerAlgorithmRingDashesEnabled( bool enabled );

    /**
      * Sets the render color of the 'Algorithm' threat ring.
      * \param ringColor  The color to use when rendering the threat ring
      */
    void SetThreatLayerAlgorithmRingColor( glsColor& ringColor );

    /**
      * Sets the render color of the 'Lethality' threat ring.
      * \param ringColor  The color to use when rendering the threat ring
      */
    void SetThreatLayerLethalityRingColor( glsColor& ringColor );

    /**
      * Sets the render color of the 'Detection' threat ring.
      * \param ringColor  The color to use when rendering the threat ring
      */
    void SetThreatLayerDetectionRingColor( glsColor& ringColor );

    /**
      * Sets the thickness of the 'Algorithm' threat ring, in pixels.
      * \param lineThickness  The threat ring line thickness in pixels
      */
    void SetThreatLayerAlgorithmRingThickness( unsigned char lineThickness );

    /**
      * Sets the thickness of the 'Lethality' threat ring, in pixels.
      * \param lineThickness  The threat ring line thickness in pixels
      */
    void SetThreatLayerLethalityRingThickness( unsigned char lineThickness );

    /**
      * Sets the thickness of the 'Detection' threat ring, in pixels.
      * \param lineThickness  The threat ring line thickness in pixels
      */
    void SetThreatLayerDetectionRingThickness( unsigned char lineThickness );

    /**
      * \returns whether the worker threads have finished running
      * \param rect  The region that all cells that should be done with are in
      */
    bool HasWorkerThreadFinishedForArea( const GeoRect& rect );

    void RemoveData( void );

private:
    // A container that holds all of our elevation data
    DTEDElevationDataStore* _dataStore;

    // A container that holds and manages the computation parameters
    DTEDCalcParamsStore* _paramsStore;

    // A container that holds all of the map cells
    DTEDMapChartCellManager* _mapCellManager;

    // Worker thread for loading dted files from disk
    DTEDFileLoadThread* _fileLoadThread;

    // A container that holds a group of worker threads for cell computations
    DTEDWorkerThreadManager* _workerManager;

    // A container that holds the shaders that this map uses for rendering
    DTEDShaderManager* _shaderManager;
};
/// @}
} // namespace disti

#endif