text: /*
  -----------------------------------------------------------------------------
  This source file is part of OGRE
  (Object-oriented Graphics Rendering Engine)
  For the latest info, see http://www.ogre3d.org/
  
  Copyright (c) 2000-2005 The OGRE Team
  Also see acknowledgements in Readme.html
  
  This program 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, write to the Free Software Foundation, Inc., 59 Temple
  Place - Suite 330, Boston, MA 02111-1307, USA, or go to
  http://www.gnu.org/copyleft/lesser.txt.
  -----------------------------------------------------------------------------
  */
  /***************************************************************************
  terrainscenemanager.h  -  description
  ---------------------
    begin                : Mon Sep 23 2002
    copyright            : (C) 2002 by Jon Anderson
    email                : janders@users.sf.net
  
    Enhancements 2003 - 2004 (C) The OGRE Team
  
  ***************************************************************************/
  
  #ifndef TERRAINSCENEMANAGER_H
  #define TERRAINSCENEMANAGER_H
  
  #include "OgreTerrainPrerequisites.h"
  #include "OgreOctreeSceneManager.h"
  #include "OgreOctreeSceneQuery.h"
  #include "OgreTerrainRenderable.h"
  #include "OgreTerrainPageSource.h"
  #include "OgreIteratorWrappers.h"
  
  
  namespace Ogre
  {
  
  class Image;
  
  typedef std::vector < TerrainPage * > TerrainPageRow;
  typedef std::vector < TerrainPageRow > TerrainPage2D;
  
  /** Default implementation of RaySceneQuery. */
  class _OgreTerrainExport TerrainRaySceneQuery : public OctreeRaySceneQuery
  {
  protected:
  	WorldFragment mWorldFrag;
  public:
      TerrainRaySceneQuery(SceneManager* creator);
      ~TerrainRaySceneQuery();
  
      /** See RayScenQuery. */
      void execute(RaySceneQueryListener* listener);
  };
  
  
  
  /** This is a basic SceneManager for organizing TerrainRenderables into a total landscape.
    * It loads a terrain from a .cfg file that specifices what textures/scale/mipmaps/etc to use.
    *@author Jon Anderson
    */
  
  class _OgreTerrainExport TerrainSceneManager : public OctreeSceneManager
  {
  public:
      TerrainSceneManager(const String& name);
      virtual ~TerrainSceneManager( );
  
  	/// @copydoc SceneManager::getTypeName
  	const String& getTypeName(void) const;
  
      /** Loads the terrain using parameters int he given config file. */
      void setWorldGeometry( const String& filename );
      /** Loads the terrain using parameters in the given config file (contained 
  		in a stream). */
  	virtual void setWorldGeometry(DataStreamPtr& stream, 
  		const String& typeName = StringUtil::BLANK);
  
      /** Aligns TerrainRenderable neighbors, and renders them. */
      virtual void _renderVisibleObjects( void );
  
      /** Returns the height at the given terrain coordinates. */
      float getHeightAt( float x, float y );
  
  
      bool intersectSegment( const Vector3 & start, const Vector3 & end, Vector3 * result );
  
      /** Sets the texture to use for the main world texture. */
      void setWorldTexture(const String& textureName);
      /** Sets the texture to use for the detail texture. */
      void setDetailTexture(const String& textureName);
      /** Sets the number of times per tile the detail texture should be repeated. */
      void setDetailTextureRepeat(int repeat);
      /** Sets the dimensions of each tile (must be power of 2 + 1) */
      void setTileSize(int size); 
      /** Sets the dimensions of each page (must be power of 2 + 1) */
      void setPageSize(int size); 
      /** Sets the maximum screen space pixel error.  */
      void setMaxPixelError(int pixelError); 
      /** Sets how to scale the terrain data. */
      void setScale(const Vector3& scale);
      /** Sets the maximum geomipmap level to allow. */
      void setMaxGeoMipMapLevel(int maxMip);
      
      /** Gets the texture to use for the main world texture. */
      const String& getWorldTexture(void) { return mWorldTextureName; }
      /** Gets the texture to use for the detail texture. */
      const String& getDetailTexture(void) { return mDetailTextureName; }
      /** Gets the number of times per tile the detail texture should be repeated. */
      int getDetailTextureRepeat(void);
      /** Gets the dimensions of each tile (must be power of 2 + 1) */
      int getTileSize(void); 
      /** Gets the dimensions of each page (must be power of 2 + 1) */
      int getPageSize(void); 
      /** Gets the maximum screen space pixel error.  */
      int getMaxPixelError(void); 
      /** Gets how to scale the terrain data. */
      const Vector3& getScale(void);
      /** Gets the maximum geomipmap level to allow. */
      int getMaxGeoMipMapLevel(void);
  
  
  
      /** Sets whether the terrain should use triangle strips or not.
      @remarks
          The default is not, in which case it uses triangle lists. 
      */
      void setUseTriStrips(bool useStrips);
      /** Sets whether or not terrain tiles should be morphed between LODs
      (NB requires vertex program support). */
      void setUseLODMorph(bool useMorph);
      /** Sets whether vertex normals will be generated for the terrain. */
      void setUseVertexNormals(bool useNormals);
      /** Sets whether vertex colours will be used. */
      void setUseVertexColours(bool useColours);
  
      /** Sets the name of a custom material to use to shade the landcape.
      @remarks
          This method allows you to provide a custom material which will be
          used to render the landscape instead of the standard internal 
          material. This gives you a great deal of flexibility and allows you 
          to perform special effects if you wish. Note that because you determine
          every aspect of the material, this setting makes the use of setWorldTexture
          and setDetailTexture redundant.
      @par
          In your custom material, you can use all the usual features of Ogre's
          materials, including multiple passes if you wish. You can also use 
          the programmable pipeline to hook vertex and fragment programs into the
          terrain rendering. The plugin provides the following vertex components:
          <ul>
              <li>positions</li>
              <li>2 sets of texture coordinates (index 0 is world texture, 
              index 1 is detail texture)</li>
              <li>Normals, if enabled</li>
              <li>Per-vertex delta values, for morphing a higher LOD tile into 
                  a lower LOD tile. This is one float per vertex bound as 'blend
                  weight'. If you want to use this you also have to provide the
                  name or index of the parameter you wish to receive the morph factor
                  (@see setCustomMaterialMorphFactorParam)</li>
          </ul>
      */
      void setCustomMaterial(const String& materialName);
      /** Sets the name of the vertex program parameter to which to pass the
          LOD morph factor.
      @remarks
          When LOD morphing is enabled, and you are using a custom material to 
          shade the terrain, you need to inform this class of the parameter you
          wish the current LOD morph factor to be passed to. This is a simple
          float parameter value that the plugin will set from 0 to 1, depending on
          the morph stage of a tile. 0 represents no morphing, ie the vertices are
          all in the original position. 1 represents a complete morph such that
          the height of the vertices is the same as they are at the next lower LOD
          level. The vertex program must use this factor, in conjunction with the
          per-vertex height delta values (bound as 'blend weight'), to displace
          vertices.
      @note This version of the method lets you specify a parameter name, compatible
          with high-level vertex programs. There is an alternative signature method
          which allows you to set the parameter index for low-level assembler programs.
      @param paramName The name of the parameter which will receive the morph factor
      */
      void setCustomMaterialMorphFactorParam(const String& paramName);
      /** Sets the index of the vertex program parameter to which to pass the
          LOD morph factor.
      @remarks
          When LOD morphing is enabled, and you are using a custom material to 
          shade the terrain, you need to inform this class of the parameter you
          wish the current LOD morph factor to be passed to. This is a simple
          float parameter value that the plugin will set from 0 to 1, depending on
          the morph stage of a tile. 0 represents no morphing, ie the vertices are
          all in the original position. 1 represents a complete morph such that
          the height of the vertices is the same as they are at the next lower LOD
          level. The vertex program must use this factor, in conjunction with the
          per-vertex height delta values (bound as 'blend weight'), to displace
          vertices.
      @note This version of the method lets you specify a parameter index, compatible
          with low-level assembler vertex programs. There is an alternative signature method
          which allows you to set the parameter name for high-level programs.
      @param paramName The name of the parameter which will receive the morph factor
      */
      void setCustomMaterialMorphFactorParam(size_t paramIndex);
      /** Sets the distance at which the LOD will start to morph downwards, as
      a proportion of the distance between the LODs. */
      void setLODMorphStart(Real morphStart);
  
      /** Returns the TerrainRenderable that contains the given pt.
          If no tile exists at the point, it returns 0;
      */
      virtual TerrainRenderable * getTerrainTile( const Vector3 & pt );
  
      /** Returns the TerrainPage that contains the given pt.
      If no page exists at the point, it returns 0;
      */
      virtual TerrainPage* getTerrainPage( const Vector3 & pt );
  
      /** Creates a RaySceneQuery for this scene manager. 
      @remarks
          This method creates a new instance of a query object for this scene manager, 
          looking for objects which fall along a ray. See SceneQuery and RaySceneQuery 
          for full details.
      @par
          The instance returned from this method must be destroyed by calling
          SceneManager::destroyQuery when it is no longer required.
      @param ray Details of the ray which describes the region for this query.
      @param mask The query mask to apply to this query; can be used to filter out
          certain objects; see SceneQuery for details.
      */
      RaySceneQuery* 
          createRayQuery(const Ray& ray, unsigned long mask = 0xFFFFFFFF);
  
      /** Overridden in order to store the first camera created as the primary
          one, for determining error metrics and the 'home' terrain page.
      */
      Camera* createCamera( const String &name );
      /// Gets the terrain options 
      const TerrainOptions& getOptions(void) { return mOptions; }
  
      /** Sets the given option for the SceneManager.
      @remarks
          Options are (in addition to those supported by superclasses):
          "PageSize", int*;
          "TileSize", int*; 
          "PrimaryCamera, Camera*;
          "MaxMipMapLevel", int*;
          "Scale", Vector3 *;
          "MaxPixelError", int*;
          "UseTriStrips", bool*;
          "VertexProgramMorph", bool*;
          "DetailTile", int*;
          "LodMorphStart", Real*;
          "VertexNormals", bool*;
          "VertexColours", bool*;
          "MorphLODFactorParamName", String*;
          "MorphLODFactorParamIndex", size_t*;
          "CustomMaterialName", String*;
          "WorldTexture", String*;
          "DetailTexture", String*;
      */
      virtual bool setOption( const String &, const void * );
  
      /** Sets the 'primary' camera, i.e. the one which will be used to determine
          the 'home' terrain page, and to calculate the error metrics. 
      */
      virtual void setPrimaryCamera(const Camera* cam);
      /// Internal map of page source name to page source
      typedef std::map<String, TerrainPageSource*> PageSourceMap;
  
      /// Iterator over all page sources
      typedef ConstMapIterator<PageSourceMap> PageSourceIterator;
      /// Get an iterator over all page sources
      PageSourceIterator getPageSourceIterator(void);
      /** Registers a TerrainPageSource class and associates it with a named type 
          of source.
      @remarks
          This function allows external classes to register themselves as providers
          of terrain pages of a particular type. Only one page source can be
          active at once, and the active one is selected by calling 
          selectPageSource(typeName), which is part of plugin configuration.
      @note The terrain engine comes with a default page source which loads
          greyscale heightmap images, registered under the type name "Heightmap".
      @param typeName A unique String to associate with this type of source
      @param source Pointer to the class which will implement this source.
      */
      virtual void registerPageSource(const String& typeName, TerrainPageSource* source);
      /** Selects a given page source based on its type name.
      @remarks
          This method activates a single page source based on its typename, 
          e.g. "Heightmap". It also passes to it a number of custom options
          which the source is able to interpret however it likes.
      @param typeName The type name of the page source to activate
      @param optionList A list of string parameters, which are expected to begin
          with 'typeName.' (e.g. "Heightmap.image"), with their appropriate
          values.
      */
      virtual void selectPageSource(const String& typeName, 
          TerrainPageSourceOptionList& optionList);
  
      /** Attaches a previously built page to the list of available pages.
      @remarks
          TerrainPageSource subclasses will call this method once they have
          pages available to be added to the working set. Note that whilst you
          can build TerrainPage instances in another thread if you like, this
          method must be called in the same thread as the main rendering loop 
          in order to avoid concurrency issues. 
      @param pageX, pageZ The page index at which to attach the page
      @param page The page to attach
      */
      virtual void attachPage(ushort pageX, ushort pageZ, TerrainPage* page);
      /// Get a pointer to the material being used for the terrain
      MaterialPtr& getTerrainMaterial(void);
      // Overridden from basic scene manager
      void _renderScene(Camera *cam, Viewport *vp, bool includeOverlays);
  
      /// Get the SceneNode under which all terrain nodes are attached.
      SceneNode* getTerrainRootNode(void) const { return mTerrainRoot; }
      /** Overridden from SceneManager */
      void clearScene(void);
  	/** Overridden from SceneManager */
  	void setWorldGeometryRenderQueue(uint8 qid);
  
  	/// Get the shared list of indexes cached (internal use only)
  	TerrainBufferCache& _getIndexCache(void) {return mIndexCache;}
  
  	/// Get the shared level index list (internal use only)
  	LevelArray& _getLevelIndex(void) { return mLevelIndex; }
  
  	/// Get the current page count (internal use only)
  	size_t _getPageCount(void) { return mTerrainPages.size(); }
  
  	/// Shutdown cleanly before we get destroyed
  	void shutdown(void);
  
  
  protected:
  
      /// Validates that the size picked for the terrain is acceptable
      bool _checkSize( int s )
      {
          for ( int i = 0; i < 16; i++ )
          {
              printf( "Checking...%d\n", ( 1 << i ) + 1 );
  
              if ( s == ( 1 << i ) + 1 )
                  return true;
          }
  
          return false;
  
      }
  
      /// The node to which all terrain tiles are attached
      SceneNode * mTerrainRoot;
      /// Terrain size, detail etc
      TerrainOptions mOptions;
      /// Should we use an externally-defined custom material?
      bool mUseCustomMaterial;
      /// The name of the custom material to use
      String mCustomMaterialName;
      /// The name of the world texture
      String mWorldTextureName;
      /// The name of the detail texture
      String mDetailTextureName;
      /// Are we using a named parameter to hook up LOD morph?
      bool mUseNamedParameterLodMorph;
      /// The name of the parameter to send the LOD morph to
      String mLodMorphParamName;
      /// The index of the parameter to send the LOD morph to
      size_t mLodMorphParamIndex;
      /// Whether paging is enabled, or whether a single page will be used
      bool mPagingEnabled;
      /// The number of pages to render outside the 'home' page
      unsigned short mLivePageMargin;
      /// The number of pages to keep loaded outside the 'home' page
      unsigned short mBufferedPageMargin;
      /// Grid of buffered pages
      TerrainPage2D mTerrainPages;
  	//-- attributes to share across tiles
  	/// Shared list of index buffers
  	TerrainBufferCache mIndexCache;
  	/// Shared array of IndexData (reuse indexes across tiles)
  	LevelArray mLevelIndex;
      
      /// Internal method for loading configurations settings
      void loadConfig(DataStreamPtr& stream);
  
      /// Sets up the terrain material
      void setupTerrainMaterial(void);
      /// Sets up the terrain page slots
      void setupTerrainPages(void);
  	/// Initialise level indexes
  	void initLevelIndexes(void);
  	/// Destroy level indexes
  	void destroyLevelIndexes(void);
  
  
      /// Map of source type -> TerrainPageSource
      PageSourceMap mPageSources;
      /// The currently active page source
      TerrainPageSource* mActivePageSource;
  
  };
  /// Factory for TerrainSceneManager
  class TerrainSceneManagerFactory : public SceneManagerFactory
  {
  protected:
  	typedef std::vector<TerrainPageSource*> TerrainPageSources;
  	TerrainPageSources mTerrainPageSources;
  	void initMetaData(void) const;
  public:
  	TerrainSceneManagerFactory();
  	~TerrainSceneManagerFactory();
  	/// Factory type name
  	static const String FACTORY_TYPE_NAME;
  	SceneManager* createInstance(const String& instanceName);
  	void destroyInstance(SceneManager* instance);
  };
  
  }
  
  #endif
  