/* -*-c++-*- */
/* osgEarth - Dynamic map generation toolkit for OpenSceneGraph
 * Copyright 2008-2010 Pelican Mapping
 * http://osgearth.org
 *
 * osgEarth is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>
 */
#ifndef OSGEARTHUTIL_ELEVATION_MANAGER_H
#define OSGEARTHUTIL_ELEVATION_MANAGER_H

#include <osgEarthUtil/Common>
#include <osgEarth/Map>
#include <osgEarth/MapNode>

namespace osgEarth { namespace Util
{
    using namespace osgEarth;

    /**
     * ElevationManager (EM) lets you query the elevation at any point on a terrain map.
     * 
     * Rather than intersecting with a loaded scene graph, EM uses the osgEarth
     * engine to directly access the best terrain tile for elevation query. You
     * give it the DEM resolution at which you want an elevation point, and it will
     * access the necessary tile and sample it.
     *
     * EM supports two types of sampling:
     *
     * PARAMTERIC - EM will sample the actual heightfield directly. This method is the
     *   fastest since it does not require geometry intersection testing.
     * GEOMETRIC - EM will create a temporary tesselated terrain tile and do an 
     *   intersection test (using osgUtil::IntersectionVisitor). This method is slower
     *   but more visually correlated.
     *
     * NOTE: EM does NOT take into account rendering properties like vertical scale or
     * skirts. If you need a vertical scale, for example, simply scale the resulting
     * elevation value.
     */
    class OSGEARTHUTIL_EXPORT ElevationManager : public osg::Referenced
    {
    public:
        /** Technique for elevation data sampling - see setTechnique */
        enum Technique
        {
            /** Intersect with triangulated geometry - using the highest resolution
                data available from the Map source layers */
            TECHNIQUE_GEOMETRIC,

            /** Sample height from the parametric heightfield directly (bilinear) */
            TECHNIQUE_PARAMETRIC
        };

    public:
        /**
         * Constructs a new elevation manager. If you are not using a MapNode,
         * use this constructor to perform elevation queries against a Map. If
         * you *do* have a MapNode, use the other CTOR that takes a MapNode.
         *
         * @param map
         *      Map against which to perform elevation queries.
         * @param technique
         *      Technique to use for elevation data sampling.
         */
        ElevationManager( Map* map );

        /**
         * Gets the terrain elevation at a point, given a terrain resolution.
         *
         * @param x, y
         *      Map coordinates for which to query elevation.
         * @param resolution
         *      Optimal resolution of elevation data to use for the query (if available).
         *      Pass in 0 (zero) to use the best available resolution.
         * @param srs
         *      Spatial reference of x, y, and resolution. If this is NULL, assume that 
         *      the input values are expressed in terms of the Map's SRS.
         * @param out_elevation
         *      Resulting elevation value (if the method returns true.)
         * @param out_resolution
         *      Resolution of the resulting elevation value (if the method returns true).
         * 
         * @return True if the query succeeded, false upon failure.
         */
        bool getElevation(
            double x, double y,
            double resolution,
            const SpatialReference* srs,
            double& out_elevation,
            double& out_resolution);

        /**
         * Gets a matrix that you can use to position a node at the specified coordinates.
         * The elevation of the object will be the ground height + the specified Z value.
         * The ground height will be determined by using getElevation() with the 
         * specified resolution.
         *
         * Returns TRUE if the output matrix is valid.
         */
        bool getPlacementMatrix(
            double x, double y, double z,
            double resolution,
            const SpatialReference* srs,
            osg::Matrixd& out_matrix,
            double& out_elevation,
            double& out_resolution);

        /**
         * Sets the technique to use for height determination. See the Technique
         * enum in this class. The default is TECHNIQUE_PARAMETRIC.
         */
        void setTechnique( Technique technique );

        /**
         * Gets the technique to use for height determination. See the Technique
         * enum in this class.
         */
        Technique getTechnique() const;

        /**
         * Sets the maximum cache size for elevation tiles.
         */
        void setMaxTilesToCache( int value );

        /**
         * Gets the maximum cache size for elevation tiles.
         */
        int getMaxTilesToCache() const;

        /**
         * Sets the elevation interpolation to use when sampling data
         */
        void setInterpolation( ElevationInterpolation interp );

        /**
         * Gets the elevation interpolation to use when sampling data
         */
        ElevationInterpolation getElevationInterpolation() const;

    private:
        MapFrame _mapf;
        typedef std::map< osgTerrain::TileID, osg::ref_ptr<osgTerrain::TerrainTile> > TileTable;
        TileTable _tileCache;
        typedef std::list< osgTerrain::TileID > TileIdList;
        TileIdList _tileCacheFIFO;
        int _maxCacheSize;
        int _tileSize;
        unsigned int _maxDataLevel;
        Technique _technique;
        ElevationInterpolation _interpolation;

    private:
        void postCTOR();
        void sync();

        bool getElevationImpl(
            double x, double y,
            double resolution,
            const SpatialReference* srs,
            double& out_elevation,
            double& out_resolution);
    };

} } // namespace osgEarth::Util

#endif // OSGEARTHUTIL_ELEVATION_MANAGER_H

