source: GTP/trunk/Lib/Geom/OgreStuff/include/opt/OgreTerrainPageSource.h @ 1809

Revision 1809, 12.1 KB checked in by gumbau, 18 years ago (diff)
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4(Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25
26#ifndef __TerrainPageSource_H__
27#define __TerrainPageSource_H__
28
29#include "OgreTerrainPrerequisites.h"
30#include "OgreSingleton.h"
31
32namespace Ogre {
33
34    typedef std::pair<String, String> TerrainPageSourceOption;
35    typedef std::vector<TerrainPageSourceOption> TerrainPageSourceOptionList;
36
37    /** Abstract class which classes can override to receive notifications
38        when a page is ready to be added to the terrain manager.
39    */
40    class _OgreTerrainExport TerrainPageSourceListener
41    {
42    public:
43        /** Listener method called when a new page is about to be constructed.
44                @param manager The manager in question
45        @param pagex, pagez The index of the page being constructed
46        @param heightData Array of normalised height data (0..1). The size of
47            this buffer will conform to the scene manager page size. The listener
48            may modify the data if it wishes.
49        */
50        virtual void pageConstructed(TerrainSceneManager* manager, size_t pagex, size_t pagez, Real* heightData) = 0;
51    };
52
53        /** Simple manager class to hold onto a list of page source listeners
54            across all sources.
55        */
56        class _OgreTerrainExport TerrainPageSourceListenerManager :
57                public Singleton<TerrainPageSourceListenerManager>
58        {
59        protected:
60        typedef std::vector<TerrainPageSourceListener*> PageSourceListenerList;
61        PageSourceListenerList mPageSourceListeners;
62        public:
63        TerrainPageSourceListenerManager() {}
64        ~TerrainPageSourceListenerManager() {}
65
66        /** Register a class which will be called back whenever a new page is
67            available.
68        @remarks
69            Since this method is static, it applies to any page source which
70            is in active use; there is no need to register one per source.
71        */
72        void addListener(TerrainPageSourceListener* pl);
73        /** Unregister a class which will be called back whenever a new page is
74        available.
75        */
76        void removeListener(TerrainPageSourceListener* pl);
77               
78        /// Fire pageContructed events
79        void firePageConstructed(TerrainSceneManager* manager, size_t pagex, size_t pagez, Real* heightData);
80
81       /** Override standard Singleton retrieval.
82        */
83        static TerrainPageSourceListenerManager& getSingleton(void);
84        /** Override standard Singleton retrieval.
85        */
86        static TerrainPageSourceListenerManager* getSingletonPtr(void);
87       
88        };
89
90
91    /** Abstract class which describes the interface which a source of terrain
92        pages must implement.
93    @remarks
94        The TerrainSceneManager can accept external classes as providers of
95        terrain data, to allow terrain height data to come from anywhere the
96        user application may choose, and additionally to support on-demand
97        loading an unloading of terrain data. Providers must suclass this class,
98        and implement the abstract methods (details are described within each method)
99    @par
100        The overall sequence of events is this:
101        <ol>
102        <li>TerrainSceneManager is created as usual, and options such as tile
103        size etc are set.</li>
104        <li>CustomTerrainPageSource is registered with TerrainSceneManager by
105        calling registerPageSource(), registering a particular named type of source
106        data with this tile source. <li>
107        <li>TerrainSceneManager::setWorldGeometry is called. Depending on the
108        configuration, this will call one of the page source classes
109        initialise methods, when the scene manager will communicate it's
110        preferred options. It does not have to load anything immediately on this
111        call (especially if the terrain options include paging). It will
112        also set this tile source as the primary.<li>
113        <li>As and when TerrainSceneManager requires more tiles (and this will
114        either be done all up-front, or progressively depending on paging settings)
115        it will call the primary tile source's requestPage() method, with the
116        page it requires. </li>
117        <li>It is then the responsibility of the tile source to prepare
118        TerrainRenderable instances for the page(s) requested, and to attach them
119        to the TerrainSceneManager. Note that preparing the tiles does not
120        involve modifying any shared data so may be done in an alternate thread,
121        if required. Attaching them must be done synchronously though.
122        <li>When paging, the TerrainSceneManager will request tiles in advance,
123        within it's 'buffer zone' so some delay in loading is acceptable. It
124        will also indicate when tiles are no longer required (and will detach
125        them); it is up to the tile source whether that memory is actually freed
126        or held for a while longer.
127        </ol>
128    @note The comments on paging above are in principle, the implementation of
129    paging in this manager is not present yet but the system is designed to
130    extend to it. For now, all tiles are requested up-front.
131    */
132    class _OgreTerrainExport TerrainPageSource
133    {
134    protected:
135        /// Link back to parent manager
136        TerrainSceneManager* mSceneManager;
137        /// Has asynchronous loading been requested?
138        bool mAsyncLoading;
139        /// The expected size of the page in number of vertices
140        unsigned short mPageSize;
141        /// The expected size of a tile in number of vertices
142        unsigned short mTileSize;
143
144        /// Internal method for firing pageContructed events
145        void firePageConstructed(size_t pagex, size_t pagez, Real* heightData);
146
147        /** Utility method for building a page of tiles based on some source
148        data, wherever that may have come from.
149        @remarks
150            It is expected that this height data is represented in the range
151            [0..1], which will be duly scaled by the TerrainRenderables it
152            creates.
153        */
154        virtual TerrainPage* buildPage(Real* heightData, const MaterialPtr& pMaterial);
155
156
157    public:
158        TerrainPageSource();
159        virtual ~TerrainPageSource() { shutdown(); }
160
161        /** Initialise this tile source based on a series of options as
162            dictated by the scene manager.
163        @param tsm The TerrainSceneManager doing the initialising. This should be
164            allowed NULL, for use by external tools if they want to read data
165            generically without necessarily having a real scene manager involved
166        @param tileSize The number of horizontal (and hence also vertical)
167            vertices in a single tile (which is a TerrainRenderable). This will
168            always be (2^n)+1.
169        @param pageSize The number of horizontal (and hence also vertical)
170            vertices in a single page. This will always be (2^n)+1.
171        @param asyncLoading
172            True if the scene manager would like the tile source to load tiles
173            asynchronously. It does not have to do this, although if it does not
174            when requested, it will likely result in stalls in the terrain rendering.
175        @param optionList
176            A list of name/value pairs describing custom options for this particular
177            page source. The expected convention for option names is
178            "TypeName.OptionName", where TypeName is the type under which this
179            page source has been registered.
180        */
181        virtual void initialise(TerrainSceneManager* tsm,
182            ushort tileSize, ushort pageSize, bool asyncLoading,
183            TerrainPageSourceOptionList& optionList)
184        {
185            mSceneManager = tsm;
186            mTileSize = tileSize;
187            mPageSize = pageSize;
188            mAsyncLoading = asyncLoading;
189        }
190        /** Shut down this tile source, freeing all it's memory ready for
191            decommissioning.
192        @remarks
193            This method will normally just be called on destruction; however
194            it may also be called by the TerrainSceneManager if another source
195            is provided for the same type of tile source.
196        */
197        virtual void shutdown(void) {}
198
199        /** Requests a new page of tiles from the source.
200        @remarks
201            The TerrainSceneManager will call this method when it needs new tiles.
202            In response, this class must prepare TerrainRenderable instances for
203            the page requested and attach the entire page when ready using
204            TerrainSceneManager::attachTerrainPage.
205        @par
206            Now, the tile source does not necessarily need to do all that before the
207            return of this method. If it likes, and particularly if asynchronous
208            loading is enabled, it can merely queue this request, and process it
209            either in another thread, or over a series of frames. The key thing
210            is that attaching the new page has to be done synchronously with
211            the main rendering loop in order to avoid concurrency issues;
212            other than that, you are free to load and prepare new tiles in
213            a concurrent fashion if you like.
214        @par
215            Typically the scene manager will request at least one page up-front,
216            with the possibility of requesting more if paging is enabled.
217        @param x The x index of the page requested
218        @param z The z index of the page requested
219        */
220        virtual void requestPage(ushort x, ushort z) = 0;
221        /** This notifies the tile source that the specified page of tiles
222            has been automatically detached.
223        @remarks
224            When paging is enabled, tiles go out of scope and the TerrainSceneManager
225            detaches them automatically, notifying the TerrainPageSource that
226            this has happened. The tile source can choose to either keep these
227            tiles in memory (incase they are requested again) or can delete them
228            if it wishes to free memory. This freeing does not need to be done
229            before the return of this method - like requesting tiles, the
230            freeing of them can be done in another thread or across many frames
231            if required, since the shared data in TerrainSceneManager has already
232            been updated synchronously when the page was detached.
233        @param x The x index of the page expired
234        @param z The z index of the page expired
235        */
236        virtual void expirePage(ushort x, ushort z) = 0;
237       
238        /** Register a class which will be called back whenever a new page is
239            available.
240        @remarks
241            Since this method is static, it applies to any page source which
242            is in active use; there is no need to register one per source.
243        */
244        static void addListener(TerrainPageSourceListener* pl);
245        /** Unregister a class which will be called back whenever a new page is
246        available.
247        */
248        static void removeListener(TerrainPageSourceListener* pl);
249
250    };
251
252}
253
254#endif
Note: See TracBrowser for help on using the repository browser.