/* ----------------------------------------------------------------------------- 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. ----------------------------------------------------------------------------- */ /* ----------------------------------------------------------------------------- This source file is part of the GameTools Project http://www.gametools.org Author: Martin Szydlowski ----------------------------------------------------------------------------- */ #ifndef __KdTerrainPageSource_H__ #define __KdTerrainPageSource_H__ #include #include "OgreKdTerrainPrerequisites.h" namespace Ogre { typedef std::pair KdTerrainPageSourceOption; typedef std::vector KdTerrainPageSourceOptionList; /** Abstract class which classes can override to receive notifications when a page is ready to be added to the terrain manager. */ class _OgreKdTerrainExport KdTerrainPageSourceListener { public: /** Listener method called when a new page is about to be constructed. @param manager The manager in question @param pagex, pagez The index of the page being constructed @param heightData Array of normalised height data (0..1). The size of this buffer will conform to the scene manager page size. The listener may modify the data if it wishes. */ virtual void pageConstructed(KdTerrainSceneManager* manager, uint pagex, uint pagez, Real* heightData) = 0; }; /** Simple manager class to hold onto a list of page source listeners across all sources. */ class _OgreKdTerrainExport KdTerrainPageSourceListenerManager : public Singleton { protected: typedef std::vector KdPageSourceListenerList; KdPageSourceListenerList mPageSourceListeners; public: KdTerrainPageSourceListenerManager() {} ~KdTerrainPageSourceListenerManager() {} /** Register a class which will be called back whenever a new page is available. @remarks Since this method is static, it applies to any page source which is in active use; there is no need to register one per source. */ void addListener(KdTerrainPageSourceListener* pl); /** Unregister a class which will be called back whenever a new page is available. */ void removeListener(KdTerrainPageSourceListener* pl); /// Fire pageContructed events void firePageConstructed(KdTerrainSceneManager* manager, uint pagex, uint pagez, Real* heightData); /** Override standard Singleton retrieval. */ static KdTerrainPageSourceListenerManager& getSingleton(void); /** Override standard Singleton retrieval. */ static KdTerrainPageSourceListenerManager* getSingletonPtr(void); }; /** Abstract class which describes the interface which a source of terrain pages must implement. @remarks The TerrainSceneManager can accept external classes as providers of terrain data, to allow terrain height data to come from anywhere the user application may choose, and additionally to support on-demand loading an unloading of terrain data. Providers must suclass this class, and implement the abstract methods (details are described within each method) @par The overall sequence of events is this:
  1. TerrainSceneManager is created as usual, and options such as tile size etc are set.
  2. CustomTerrainPageSource is registered with TerrainSceneManager by calling registerPageSource(), registering a particular named type of source data with this tile source.
  4. TerrainSceneManager::setWorldGeometry is called. Depending on the configuration, this will call one of the page source classes initialise methods, when the scene manager will communicate it's preferred options. It does not have to load anything immediately on this call (especially if the terrain options include paging). It will also set this tile source as the primary.
  6. As and when TerrainSceneManager requires more tiles (and this will either be done all up-front, or progressively depending on paging settings) it will call the primary tile source's requestPage() method, with the page it requires.
  7. It is then the responsibility of the tile source to prepare TerrainRenderable instances for the page(s) requested, and to attach them to the TerrainSceneManager. Note that preparing the tiles does not involve modifying any shared data so may be done in an alternate thread, if required. Attaching them must be done synchronously though.
  8. When paging, the TerrainSceneManager will request tiles in advance, within it's 'buffer zone' so some delay in loading is acceptable. It will also indicate when tiles are no longer required (and will detach them); it is up to the tile source whether that memory is actually freed or held for a while longer.
@note The comments on paging above are in principle, the implementation of paging in this manager is not present yet but the system is designed to extend to it. For now, all tiles are requested up-front. */ class _OgreKdTerrainExport KdTerrainPageSource { protected: /// Link back to parent manager KdTerrainSceneManager* mSceneManager; /// Has asynchronous loading been requested? bool mAsyncLoading; /// The expected size of the page in number of vertices uint mPageSize; /// The expected size of a tile in number of vertices uint mTileSize; /// Internal method for firing pageContructed events void firePageConstructed(uint pagex, uint pagez, Real* heightData); /** Utility method for building a page of tiles based on some source data, wherever that may have come from. @remarks It is expected that this height data is represented in the range [0..1], which will be duly scaled by the TerrainRenderables it creates. */ virtual KdTerrainPage* buildPage(Real* heightData, const MaterialPtr& pMaterial); public: KdTerrainPageSource(); virtual ~KdTerrainPageSource() { shutdown(); } /** Initialise this tile source based on a series of options as dictated by the scene manager. @param tsm The TerrainSceneManager doing the initialising. This should be allowed NULL, for use by external tools if they want to read data generically without necessarily having a real scene manager involved @param tileSize The number of horizontal (and hence also vertical) vertices in a single tile (which is a TerrainRenderable). This will always be (2^n)+1. @param pageSize The number of horizontal (and hence also vertical) vertices in a single page. This will always be (2^n)+1. @param asyncLoading True if the scene manager would like the tile source to load tiles asynchronously. It does not have to do this, although if it does not when requested, it will likely result in stalls in the terrain rendering. @param optionList A list of name/value pairs describing custom options for this particular page source. The expected convention for option names is "TypeName.OptionName", where TypeName is the type under which this page source has been registered. */ virtual void initialise(KdTerrainSceneManager* tsm, uint tileSize, uint pageSize, bool asyncLoading, KdTerrainPageSourceOptionList& optionList) { mSceneManager = tsm; mTileSize = tileSize; mPageSize = pageSize; mAsyncLoading = asyncLoading; } /** Shut down this tile source, freeing all it's memory ready for decommissioning. @remarks This method will normally just be called on destruction; however it may also be called by the TerrainSceneManager if another source is provided for the same type of tile source. */ virtual void shutdown(void) {} /** Requests a new page of tiles from the source. @remarks The TerrainSceneManager will call this method when it needs new tiles. In response, this class must prepare TerrainRenderable instances for the page requested and attach the entire page when ready using TerrainSceneManager::attachTerrainPage. @par Now, the tile source does not necessarily need to do all that before the return of this method. If it likes, and particularly if asynchronous loading is enabled, it can merely queue this request, and process it either in another thread, or over a series of frames. The key thing is that attaching the new page has to be done synchronously with the main rendering loop in order to avoid concurrency issues; other than that, you are free to load and prepare new tiles in a concurrent fashion if you like. @par Typically the scene manager will request at least one page up-front, with the possibility of requesting more if paging is enabled. @param x The x index of the page requested @param z The z index of the page requested */ virtual void requestPage(ushort x, ushort z) = 0; /** This notifies the tile source that the specified page of tiles has been automatically detached. @remarks When paging is enabled, tiles go out of scope and the TerrainSceneManager detaches them automatically, notifying the TerrainPageSource that this has happened. The tile source can choose to either keep these tiles in memory (incase they are requested again) or can delete them if it wishes to free memory. This freeing does not need to be done before the return of this method - like requesting tiles, the freeing of them can be done in another thread or across many frames if required, since the shared data in TerrainSceneManager has already been updated synchronously when the page was detached. @param x The x index of the page expired @param z The z index of the page expired */ virtual void expirePage(ushort x, ushort z) = 0; /** Register a class which will be called back whenever a new page is available. @remarks Since this method is static, it applies to any page source which is in active use; there is no need to register one per source. */ static void addListener(KdTerrainPageSourceListener* pl); /** Unregister a class which will be called back whenever a new page is available. */ static void removeListener(KdTerrainPageSourceListener* pl); }; } #endif