gls_map_chart_data_source.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsMapChartDataSource class.

  \par Copyright Information

  Copyright (c) 2017 The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 190<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_CHART_DATA_SOURCE_H
#define INCLUDED_GLS_MAP_CHART_DATA_SOURCE_H

#include "dynamic_array.h"
#include "gls_cpp_lang_support.h"
#include "gls_map_util.h"

#include <iosfwd>

namespace disti
{
class GlsMapView;
class GlsMapChart;
class GlsMapChartDataSource;

/// \brief The MapChartCell class represents an area within a 2D map.
///
/// MapChartCells are obtained from a GlsMapChartDataSource by calling the
/// GlsMapChartDataSource::GetCellList() method.
/// Each MapChartCell may provide a texture for rendering or it may use
/// it's own custom rendering method to draw its data.
/// The data needed to render the cell may not have been loaded yet,
/// the caller can set the priority of various cells to control the order
/// in which they are loaded.
class MapChartCell
{
public:
    /// Constructor
    /// \param logicalHeight The viewing height in logical space.
    MapChartCell()
        : _loadPriority( 0 )
        , _referenceCount( 1 )
        , _geoRectSet( false )
    {
    }

    /// Use this method to increment the reference count of the MapDataSource.
    virtual void AddRef()
    {
        _referenceCount++;
    }

    /// MapCells cannot be deleted directly
    /// Use this method to decrement the reference count of the MapDataSource.
    virtual void Release()
    {
        _referenceCount--;
        if( _referenceCount < 1 )
        {
            delete this;
        }
    }

    /// Instructs the MapChart Cell Manager whether to calculate and display cell outlines.
    /// \return True if the outlines should be drawn.
    ///
    virtual bool AllowOutlines() const { return true; }

    ///  Determine if this cell is still valid. Invalid cells are cells that are no longer
    /// relevant for a given data source (e.g. backing data for cell is unloaded).
    /// \return true if the cell is valid, false if the cell is not valid
    virtual bool IsCellValid() const { return true; }

    /// Returns the MapDataSource for this MapCell
    virtual GlsMapChartDataSource* GetSource() const = 0;

    /// Integer representing the layer of this image.
    /// Images from the same MapDataSource with the same Layer number all contain data
    /// at the same resolution (i.e. 'zoom level') and can be drawn together.
    virtual unsigned long GetLayerID() const { return 0; }

    /// \returns The GeoRect that describes the coverage area for the cell.
    const GeoRect& GetGeoRect() const
    {
        if( !_geoRectSet )
        {
            MapChartCell* nonConst = const_cast<MapChartCell*>( this );
            nonConst->_geoRect.SetToPoint( _lowerLeft );
            nonConst->_geoRect.GrowToContainPoint( _upperRight );
            nonConst->_geoRectSet = true;
        }

        return _geoRect;
    }

    GeoCoord& GetLowerLeftCoord() { return _lowerLeft; }
    GeoCoord& GetLowerRightCoord() { return _lowerRight; }
    GeoCoord& GetUpperLeftCoord() { return _upperLeft; }
    GeoCoord& GetUpperRightCoord() { return _upperRight; }

    /// The priority of this cell in the loading order.
    /// 0 is the highest priority.
    /// This is typically set by the CellMgr.
    virtual void         SetLoadPriority( unsigned int val ) { _loadPriority = val; }
    virtual unsigned int GetLoadPriority() const { return _loadPriority; }

    /// Determine if this cell displays a texture.
    /// If this returns true, you should call TextureIsReady() to determine
    /// if the texture data has loaded and BindTexture() to bind the texture
    /// to the current OpenGL context.
    /// \returns true if this cell is capable of loading a texture
    virtual bool HasTexture() const = 0;

    /// \returns true if BindTexture will apply a texture when called.
    virtual bool TextureIsReady() const = 0;

    /// If TextureIsReady() is true, this method will bind the texture for the cell. You must call UnbindTexture() to unbind the texture
    /// If TextureIsReady() is false, this method does nothing.
    virtual void BindTexture() = 0;

    /// Use this method to force the texture to be recreated on the next call to BindTexture().
    virtual void InvalidateTexture() = 0;

    /// The post draw callback for each cell should be called after all
    /// of the MapCell textures have been drawn to allow the MapCells to
    /// render any overlay geometry
    /// \param view The GlsMapView used to draw the chart
    /// \param chart The GlsMapChart that is being drawn
    virtual void PostDraw( GlsMapView* view, GlsMapChart* chart ) {}

    /// Determine if two MapCells are equivalent
    /// \param other Reference to the MapChartCell to compare to
    /// \returns true if the cells are equivalent, false otherwise
    virtual bool IsSameCell( const MapChartCell& other ) const = 0;

    /// Prints some information about the cell
    /// \sa MapChartCell::Write()
    friend std::ostream& operator<<( std::ostream& os, const MapChartCell& cell )
    {
        cell.Write( os ); // Call virtual function
        return os;
    }

protected:
    int          _referenceCount;
    unsigned int _loadPriority;
    GeoRect      _geoRect;
    bool         _geoRectSet;
    GeoCoord     _lowerLeft;
    GeoCoord     _lowerRight;
    GeoCoord     _upperLeft;
    GeoCoord     _upperRight;

    /// Destructor for abstract base class
    /// \note Protected for proper reference counting -- call Release() instead of destroying directly.
    virtual ~MapChartCell() {}

    /// Method to override for printing to a stream
    virtual void Write( std::ostream& os ) const;

private:
    MapChartCell( const MapChartCell& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const MapChartCell& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

/// See MapChartCell::IsSameCell
inline bool operator==( const MapChartCell& rhs, const MapChartCell& lhs )
{
    return rhs.IsSameCell( lhs );
}

typedef DynamicArray<MapChartCell*> MapChartCellList;

/** /class MapDataSource
  *
  * Abstract base class to encapsulate map library specific code and data.
  *
  * Provides a list of MapCells for a given coverage area and layer.
  * A MapDataSource may have just one layer or many layers of MapCells available.
  */
class GlsMapChartDataSource
{
public:
    /// Destructor for abstract base class
    virtual ~GlsMapChartDataSource();

    /// Sets a GeoRect to describe the area containing all areas
    /// covered by this MapDataSource.  This area may change as different
    /// databases are loaded.  Calling this method may be slow.
    /// \dest Pointer to a GeoRect to recieve the coverage.
    /// \returns true on success (dest contains the coverage description) or false if there was an error (dest is undefined)
    virtual bool GetAvailableCoverage( GeoRect* dest ) = 0;

    /// Returns the cell layer ('zoom level') that best matches the given area
    /// \param view The GlsMapView used to draw the chart
    /// \param chart The GlsMapChart that is being drawn
    /// \returns The recommended layer to use
    /// \note Data sources that do not support layers should always return 0.
    virtual unsigned long GetBestLayer( GlsMapView* view, GlsMapChart* chart ) const { return 0; }

    /// Get the list of the available cells in a given coverage area
    /// The caller will AddRef() any of the cells that it will be holding a reference to
    /// \param coverage GeoRect describing the requested area
    /// \param layerID Which layer to return MapCells from
    /// \param viewLogicalHeight The height of the view in logical units
    /// \param viewGeoHeight The height of the view in geographic units
    /// \param viewList Pointer MapChartCellList to recieve the list of available cells
    virtual void GetCellList( const GeoRect& coverage, unsigned long layerID, double viewLogicalHeight, double viewGeoHeight, MapChartCellList& viewList ) = 0;

    /// Called after all the cells have been drawn to allow the
    /// data source to perform additional rendering if needed
    /// \param view The GlsMapView used to draw the chart
    /// \param chart The GlsMapChart that is being drawn
    virtual void PostDraw( GlsMapView* view, GlsMapChart* chart ) {}

    /// Returns if all of the visible cells have finished loading and will be visible
    /// on the next frame
    /// \param view The GlsMapView used to draw the chart
    /// \param chart The GlsMapChart that is being drawn
    /// \return If all cells are loaded in a view
    virtual bool AreAllCellsLoaded( GlsMapView* view, GlsMapChart* chart );

protected:
    /// Constructor for subclasses
    GlsMapChartDataSource();

private:
    GlsMapChartDataSource( const GlsMapChartDataSource& ) DISTI_SPECIAL_MEM_FUN_DELETE;
    void operator=( const GlsMapChartDataSource& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};

// Must be defined outside the class body in C++11, but not C++14
inline GlsMapChartDataSource::GlsMapChartDataSource() {}  // = default
inline GlsMapChartDataSource::~GlsMapChartDataSource() {} // = default

} // namespace disti

#endif