gls_map_view.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsMapView 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_GLSMAPVIEW_H
#define INCLUDED_GLSMAPVIEW_H

#include "group.h"

#include "gls_map_util.h"

//////////////////// Provides support for creating DLLs ////////////////////////
#if( defined( GLSGEN_EXPORT_GLSMAPVIEW ) || defined( GLSGEN_IMPORT_GLSMAPVIEW ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSMAPVIEW ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GLSMAPVIEW_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GLSMAPVIEW_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GLSMAPVIEW_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////

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

namespace disti
{
// SetValue enumerations
enum
{
    GLS_GLSMAPVIEW_FIRST_VALUE = GLS_LAST_INITIALIZER + 1,
};

enum ProjectionType
{
    PROJECTION_TYPE_EQUIRECTANGULAR = 0,
    PROJECTION_TYPE_MERCATOR,
    PROJECTION_TYPE_TRANSVERSE_MERCATOR,
    PROJECTION_TYPE_MAX,
};

/** \brief The GlsMapView is a special group that controls the map view parameters. 
  * It contains all of the objects that are drawn into the map. 
  *
  * A GLPolygon must be included as the first child under the GlsMapView. 
  * This defines a clipping area for the map display. 
  */
class GlsMapView : public Group
{
public:
    DISTI_DEPRECATED( "This identifier is forbidden by the C++ standard. Use BaseClass instead." )
    typedef Group _BaseClass;
    typedef Group BaseClass;
    friend class GlsMapViewEditor;

    /** Create a new GlsMapView.
      * \param generateInstance  Whether or not to generate an instance name
      * for this inputdevice */
    GLSGEN_GLSMAPVIEW_EXPORT GlsMapView( bool generateInstance = false );

    /** Destructs a GlsMapView object */
    virtual GLSGEN_GLSMAPVIEW_EXPORT ~GlsMapView();

    static GLSGEN_GLSMAPVIEW_EXPORT DisplayObject* CreateInstance();

    //////////////////////////////////////////////////
    // Overridden base class methods
    //////////////////////////////////////////////////

    virtual GLSGEN_GLSMAPVIEW_EXPORT void SetAvailableAttributes( unsigned int value );
    virtual GLSGEN_GLSMAPVIEW_EXPORT DisplayObject* CloneObject( bool generateNames = false );
    virtual GLSGEN_GLSMAPVIEW_EXPORT void           CopyProperties( DisplayObject* src );

    virtual GLSGEN_GLSMAPVIEW_EXPORT InterfaceListType* GetCppInterfaceDescription( InterfaceListType* addToThisList = NULL );
    virtual GLSGEN_GLSMAPVIEW_EXPORT void               GetCppInterfaceDescriptionFree( InterfaceListType* array );

    virtual GLSGEN_GLSMAPVIEW_EXPORT void PreDraw( const OpenGLMatrices& parentMatrices, Culler& culler );
    virtual GLSGEN_GLSMAPVIEW_EXPORT void Draw( void );

    virtual GLSGEN_GLSMAPVIEW_EXPORT DisplayObject* Pick3D( const Vector& winLoc,
        const Vector&                                                     logicalCoords,
        float                                                             scale,
        const Vector&                                                     directionVector,
        Vector&                                                           collisionWinLoc /*Returned*/,
        const OpenGLMatrices&                                             drawnMatrices );

    virtual GLSGEN_GLSMAPVIEW_EXPORT DisplayObject* handle( DisplayEvent* ev );

    virtual GLSGEN_GLSMAPVIEW_EXPORT void SetValue( int spec, va_list& args );

    //////////////////////////////////////////////////
    // GlsMapView specific operations
    //////////////////////////////////////////////////

    /** Selects the projection type for the map.
      * Legacy behavior (unprojected / equirectangular / plate carree) is the default. */
    GLSGEN_GLSMAPVIEW_EXPORT void SetProjectionType( ProjectionType value );
    GLSGEN_GLSMAPVIEW_EXPORT ProjectionType GetProjectionType() const;

    /** Offset that is applied to the center of the map (in logical coordinates)
      * This does not change the geographical location being displayed by the map,
      * but rather moves the screen position that that map center is placed at. 
      * This is the point that the map rotates around when the ViewHeading changes. */
    GLSGEN_GLSMAPVIEW_EXPORT void MapCenterOffset( const Vector& value );
    Vector                        MapCenterOffset() { return _mapCenterOffset; }

    /** Set the geographical location that the map is viewing. 
      * \param value new geographic location for the map being viewed
      */
    GLSGEN_GLSMAPVIEW_EXPORT void ViewLocation( const GeoCoord& value );

    /** Get the geographical location that the map is viewing. 
      * \return GeoCoord current geographic location for the map being viewed
      */
    GeoCoord ViewLocation() { return _viewLocation; }

    /** Set the projection offset for this map.
      * This does not change the geographical location being displayed by the map,
      * but it does affect how each cell is projected. 
      * \param value the new offset to be used for projection */
    GLSGEN_GLSMAPVIEW_EXPORT void SetProjectionOffset( const GeoCoord& value );

    /** Get the projection offset that the map is viewing.
      * \return GeoCoord current projection offset for the map being viewed */
    GeoCoord GetProjectionOffset() { return _projectionOffset; };

    /** Set the rotation of the map in degrees (true north).
      * \param value desired map rotation
      */
    GLSGEN_GLSMAPVIEW_EXPORT void ViewHeading( const float& value );

    /** Get the rotation of the map in degrees (true north).
      * \return float current rotation for the map being viewed
      */
    float ViewHeading() { return _viewHeading; }

    /** Set the height of the region that the map should display in degrees latitude.
      * The width is determined from the height based on the aspect ratio of the view.
      * Use this to control the the zoom level of the map 
      * Useful conversion factors:
      * 1 degree latitude = 60 nautical miles = 111120 meters
      */
    GLSGEN_GLSMAPVIEW_EXPORT void ViewHeight( const double& value );
    double                        ViewHeight() { return _viewHeight; }

    /** When true, the contents of the map will be clipped to
      * draw only within the GlsMapView.  You may want to disable this
      * if you are using another method to clip/occlude the map. */
    GLSGEN_GLSMAPVIEW_EXPORT void ClipMap( const bool& value );
    bool                          ClipMap() { return _clipMapView; }

    /** \returns Pointer to the object that defines the plane of the map
      * or NULL if the object is not found. */
    DisplayObject* GetBackgroundObject() { return FirstObject(); }

    /** Return a GeoRect that encompasses the visible region.
      * If an object is outside of the visible region, it will not be drawn.
      */
    const GeoRect& GetVisibleRegion() const
    {
        return _visibleRegion;
    }

    /** Transform a lon/lat coordinate to the GlsMapView logical coordinates
      * \param lon longitude in degrees
      * \param lat latitude in degrees
      * \param logical_out Pointer to a Vector to receive the transformed logical coordinate
      */
    GLSGEN_GLSMAPVIEW_EXPORT void LonLatToLogical( double lon, double lat, Vector* logical_out ) const;

    /** Transform a GeoCoord coordinate to the GlsMapView logical coordinates
      * \param geo The GeoCoord to transform
      * \param logical Pointer to a Vector to receive the transformed logical coordinate
      */
    void GeoCoordToLogical( const GeoCoord& geo, Vector* logical ) const
    {
        if( !_geoToLogicalMatricesValid )
        {
            CalcGeoToLogicalMatrix();
        }

        double lon, lat, alt;
        geo.GetGeodetic( &lon, &lat, &alt );
        LonLatToLogical( lon, lat, logical );
    }

    /** Determine the GeoCoord for a given logical coordinate.
      * \param geo Vector containing the logical coordinate to transform
      * \param logical Pointer to a GeoCoord to receive the transformed coordinate
      */
    GLSGEN_GLSMAPVIEW_EXPORT void LogicalToGeoCoord( const Vector& logical, GeoCoord* geo ) const;

    /** \returns The matrix used by the GlsMapView to transform
      * lon/lat coordinates to logical coordinates.  This matrix may be used
      * to transform Vectors or applied to the OpenGL modelview matrix to
      * allow drawing by passing lon/lat coordinates directly to OpenGL. 
      * This matrix is recalculated whenever the GlsMapView is drawn. */
    const GlsMatrixAffineD& GetGeoToLogicalMatrix() const
    {
        if( !_geoToLogicalMatricesValid )
        {
            CalcGeoToLogicalMatrix();
        }
        return _geoToLogicalMatrix;
    }

    /** Get the height in logical units of the background object that defines the plane of the map
      * \return height in logical units of the background object that defines the plane of the map
      */
    double ViewLogicalHeight( void ) const
    {
        if( !_geoToLogicalMatricesValid )
        {
            CalcGeoToLogicalMatrix();
        }
        return _viewLogicalHeight;
    }

    /** This method not normally called by user.
      * It may change in future versions of GlsMapView. */
    void CalcGeoToLogicalMatrix() const;

    /** This method not normally called by user.
      * It may change in future versions of GlsMapView. */
    void CalcVisibleRegion() const;

protected:
    // GlsMapView attributes
    ProjectionType _projectionType;
    GeoCoord       _projectionOffset;

    Vector   _mapCenterOffset;
    GeoCoord _viewLocation;
    float    _viewHeading;
    double   _viewHeight;
    double   _viewLogicalHeight;

    bool _clipMapView;

    // Internal attributes and utility methods
    bool             _geoToLogicalMatricesValid;
    GlsMatrixAffineD _geoToLogicalMatrix;
    GlsMatrixAffineD _logicalToGeoMatrix;

    GeoRect _visibleRegion;

    void VisibleRegionCheckVert( const Vector& v, GeoRect& rect ) const;
};

/** Utility method to traverse up the object heirarchy
  * and find the first GlsMapView parent for a given object. */
inline GlsMapView* GetParentMapView( DisplayObject* obj )
{
    while( obj != NULL )
    {
        obj = obj->ParentGroup();

        if( dynamic_cast<GlsMapView*>( obj ) )
        {
            return (GlsMapView*)obj;
        }
    }

    return NULL;
}

} // namespace disti

#endif