Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/PlugIns/OctreeSceneManager/include/OgreTerrainPageSource.h @ 5

Last change on this file since 5 was 5, checked in by anonymous, 17 years ago

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