source: OGRE/trunk/ogrenew/PlugIns/OctreeSceneManager/include/OgreTerrainPageSource.h @ 657

Revision 657, 12.0 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

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