source: GTP/trunk/App/Demos/Geom/OgreStuff/include/OgreResourceManager.h @ 1092

Revision 1092, 16.8 KB checked in by gumbau, 18 years ago (diff)

LodStrips? and LODTrees demos

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#ifndef _ResourceManager_H__
26#define _ResourceManager_H__
27
28#include "OgrePrerequisites.h"
29
30#include "OgreResource.h"
31#include "OgreResourceGroupManager.h"
32#include "OgreIteratorWrappers.h"
33#include "OgreCommon.h"
34#include "OgreDataStream.h"
35#include "OgreStringVector.h"
36#include "OgreScriptLoader.h"
37
38namespace Ogre {
39
40    /** Defines a generic resource handler.
41    @remarks
42        A resource manager is responsible for managing a pool of
43        resources of a particular type. It must index them, look
44        them up, load and destroy them. It may also need to stay within
45        a defined memory budget, and temporaily unload some resources
46        if it needs to to stay within this budget.
47    @par
48        Resource managers use a priority system to determine what can
49        be unloaded, and a Least Recently Used (LRU) policy within
50        resources of the same priority.
51        @par
52                Resources can be loaded using the generalised load interface,
53                and they can be unloaded and removed. In addition, each
54                subclass of ResourceManager will likely define custom 'load' methods
55                which take explicit parameters depending on the kind of resource
56                being created.
57        @note
58                Resources can be loaded and unloaded through the Resource class,
59                but they can only be removed (and thus eventually destroyed) using
60                their parent ResourceManager.
61    @note
62        If OGRE_THREAD_SUPPORT is 1, this class is thread-safe.
63    */
64        class _OgreExport ResourceManager : public ScriptLoader
65    {
66    public:
67                OGRE_AUTO_MUTEX // public to allow external locking
68        ResourceManager();
69        virtual ~ResourceManager();
70
71        /** Creates a new blank resource, but does not immediately load it.
72        @remarks
73            Resource managers handle disparate types of resources, so if you want
74                        to get at the detailed interface of this resource, you'll have to
75                        cast the result to the subclass you know you're creating.
76                @param name The unique name of the resource
77                @param group The name of the resource group to attach this new resource to
78                @param isManual Is this resource manually loaded? If so, you should really
79                        populate the loader parameter in order that the load process
80                        can call the loader back when loading is required.
81                @param loader Pointer to a ManualLoader implementation which will be called
82                        when the Resource wishes to load (should be supplied if you set
83                        isManual to true). You can in fact leave this parameter null
84                        if you wish, but the Resource will never be able to reload if
85                        anything ever causes it to unload. Therefore provision of a proper
86                        ManualLoader instance is strongly recommended.
87        @param createParams If any parameters are required to create an instance,
88            they should be supplied here as name / value pairs
89        */
90        virtual ResourcePtr create(const String& name, const String& group,
91            bool isManual = false, ManualResourceLoader* loader = 0,
92            const NameValuePairList* createParams = 0);
93        /** Set a limit on the amount of memory this resource handler may use.
94            @remarks
95                If, when asked to load a new resource, the manager believes it will exceed this memory
96                budget, it will temporarily unload a resource to make room for the new one. This unloading
97                is not permanent and the Resource is not destroyed; it simply needs to be reloaded when
98                next used.
99        */
100        virtual void setMemoryBudget( size_t bytes);
101
102        /** Get the limit on the amount of memory this resource handler may use.
103        */
104        virtual size_t getMemoryBudget(void) const;
105
106                /** Unloads a single resource by name.
107                @remarks
108                        Unloaded resources are not removed, they simply free up their memory
109                        as much as they can and wait to be reloaded.
110                        @see ResourceGroupManager for unloading of resource groups.
111                */
112                virtual void unload(const String& name);
113               
114                /** Unloads a single resource by handle.
115                @remarks
116                        Unloaded resources are not removed, they simply free up their memory
117                        as much as they can and wait to be reloaded.
118                        @see ResourceGroupManager for unloading of resource groups.
119                */
120                virtual void unload(ResourceHandle handle);
121
122                /** Unloads all resources.
123                @remarks
124                        Unloaded resources are not removed, they simply free up their memory
125                        as much as they can and wait to be reloaded.
126                        @see ResourceGroupManager for unloading of resource groups.
127                */
128                virtual void unloadAll(void);
129                /** Caused all currently loaded resources to be reloaded.
130                @remarks
131                        All resources currently being held in this manager which are also
132                        marked as currently loaded will be unloaded, then loaded again.
133                */
134                virtual void reloadAll(void);
135
136                /** Remove a single resource.
137                @remarks
138                        Removes a single resource, meaning it will be removed from the list
139                        of valid resources in this manager, also causing it to be unloaded.
140                @note
141                        The word 'Destroy' is not used here, since
142                        if any other pointers are referring to this resource, it will persist
143                        until they have finished with it; however to all intents and purposes
144                        it no longer exists and will likely get destroyed imminently.
145        @note
146            If you do have shared pointers to resources hanging around after the
147            ResourceManager is destroyed, you may get problems on destruction of
148            these resources if they were relying on the manager (especially if
149            it is a plugin). If you find you get problems on shutdown in the
150            destruction of resources, try making sure you release all your
151            shared pointers before you shutdown OGRE.
152                */
153                virtual void remove(ResourcePtr& r);
154
155        /** Remove a single resource by name.
156                @remarks
157                        Removes a single resource, meaning it will be removed from the list
158                        of valid resources in this manager, also causing it to be unloaded.
159                @note
160                        The word 'Destroy' is not used here, since
161                        if any other pointers are referring to this resource, it will persist
162                        until they have finished with it; however to all intents and purposes
163                        it no longer exists and will likely get destroyed imminently.
164        @note
165            If you do have shared pointers to resources hanging around after the
166            ResourceManager is destroyed, you may get problems on destruction of
167            these resources if they were relying on the manager (especially if
168            it is a plugin). If you find you get problems on shutdown in the
169            destruction of resources, try making sure you release all your
170            shared pointers before you shutdown OGRE.
171                */
172                virtual void remove(const String& name);
173               
174                /** Remove a single resource by handle.
175                @remarks
176                        Removes a single resource, meaning it will be removed from the list
177                        of valid resources in this manager, also causing it to be unloaded.
178                @note
179                        The word 'Destroy' is not used here, since
180                        if any other pointers are referring to this resource, it will persist
181                        until they have finished with it; however to all intents and purposes
182                        it no longer exists and will likely get destroyed imminently.
183        @note
184            If you do have shared pointers to resources hanging around after the
185            ResourceManager is destroyed, you may get problems on destruction of
186            these resources if they were relying on the manager (especially if
187            it is a plugin). If you find you get problems on shutdown in the
188            destruction of resources, try making sure you release all your
189            shared pointers before you shutdown OGRE.
190                */
191                virtual void remove(ResourceHandle handle);
192                /** Removes all resources.
193                @note
194                        The word 'Destroy' is not used here, since
195                        if any other pointers are referring to these resources, they will persist
196                        until they have been finished with; however to all intents and purposes
197                        the resources no longer exist and will get destroyed imminently.
198        @note
199            If you do have shared pointers to resources hanging around after the
200            ResourceManager is destroyed, you may get problems on destruction of
201            these resources if they were relying on the manager (especially if
202            it is a plugin). If you find you get problems on shutdown in the
203            destruction of resources, try making sure you release all your
204            shared pointers before you shutdown OGRE.
205        */
206        virtual void removeAll(void);
207
208        /** Retrieves a pointer to a resource by name, or null if the resource does not exist.
209        */
210        virtual ResourcePtr getByName(const String& name);
211        /** Retrieves a pointer to a resource by handle, or null if the resource does not exist.
212        */
213        virtual ResourcePtr getByHandle(ResourceHandle handle);
214               
215                /// Returns whether the named resource exists in this manager
216                virtual bool resourceExists(const String& name)
217                {
218                        return !getByName(name).isNull();
219                }
220                /// Returns whether a resource with the given handle exists in this manager
221                virtual bool resourceExists(ResourceHandle handle)
222                {
223                        return !getByHandle(handle).isNull();
224                }
225
226                /** Notify this manager that a resource which it manages has been
227                        'touched', ie used.
228                */
229                virtual void _notifyResourceTouched(Resource* res);
230
231                /** Notify this manager that a resource which it manages has been
232                        loaded.
233                */
234                virtual void _notifyResourceLoaded(Resource* res);
235
236                /** Notify this manager that a resource which it manages has been
237                        unloaded.
238                */
239                virtual void _notifyResourceUnloaded(Resource* res);
240
241                /** Generic load method, used to create a Resource specific to this
242                        ResourceManager without using one of the specialised 'load' methods
243                        (containing per-Resource-type parameters).
244                @param name The name of the Resource
245                @param group The resource group to which this resource will belong
246                @param isManual Is the resource to be manually loaded? If so, you should
247                        provide a value for the loader parameter
248                @param loader The manual loader which is to perform the required actions
249                        when this resource is loaded; only applicable when you specify true
250                        for the previous parameter
251        @param loadParams Optional pointer to a list of name/value pairs
252            containing loading parameters for this type of resource.
253                */
254                virtual ResourcePtr load(const String& name,
255            const String& group, bool isManual = false,
256                        ManualResourceLoader* loader = 0, const NameValuePairList* loadParams = 0);
257
258                /** Gets the file patterns which should be used to find scripts for this
259                        ResourceManager.
260                @remarks
261                        Some resource managers can read script files in order to define
262                        resources ahead of time. These resources are added to the available
263                        list inside the manager, but none are loaded initially. This allows
264                        you to load the items that are used on demand, or to load them all
265                        as a group if you wish (through ResourceGroupManager).
266                @par
267                        This method lets you determine the file pattern which will be used
268                        to identify scripts intended for this manager.
269                @returns
270                        A list of file patterns, in the order they should be searched in.
271                @see isScriptingSupported, parseScript
272                */
273                virtual const StringVector& getScriptPatterns(void) const { return mScriptPatterns; }
274
275                /** Parse the definition of a set of resources from a script file.
276                @remarks
277                        Some resource managers can read script files in order to define
278                        resources ahead of time. These resources are added to the available
279                        list inside the manager, but none are loaded initially. This allows
280                        you to load the items that are used on demand, or to load them all
281                        as a group if you wish (through ResourceGroupManager).
282                @param stream Weak reference to a data stream which is the source of the script
283                @param groupName The name of the resource group that resources which are
284                        parsed are to become a member of. If this group is loaded or unloaded,
285                        then the resources discovered in this script will be loaded / unloaded
286                        with it.
287                */
288                virtual void parseScript(DataStreamPtr& stream, const String& groupName) {}
289
290                /** Gets the relative loading order of resources of this type.
291                @remarks
292                        There are dependencies between some kinds of resource in terms of loading
293                        order, and this value enumerates that. Higher values load later during
294                        bulk loading tasks.
295                */
296                virtual Real getLoadingOrder(void) const { return mLoadOrder; }
297
298                /** Gets a string identifying the type of resource this manager handles. */
299                const String& getResourceType(void) const { return mResourceType; }
300
301    protected:
302
303        /** Allocates the next handle. */
304        ResourceHandle getNextHandle(void);
305
306                /** Create a new resource instance compatible with this manager (no custom
307                        parameters are populated at this point).
308                @remarks
309                        Subclasses must override this method and create a subclass of Resource.
310                @param name The unique name of the resource
311                @param group The name of the resource group to attach this new resource to
312                @param isManual Is this resource manually loaded? If so, you should really
313                        populate the loader parameter in order that the load process
314                        can call the loader back when loading is required.
315                @param loader Pointer to a ManualLoader implementation which will be called
316                        when the Resource wishes to load (should be supplied if you set
317                        isManual to true). You can in fact leave this parameter null
318                        if you wish, but the Resource will never be able to reload if
319                        anything ever causes it to unload. Therefore provision of a proper
320                        ManualLoader instance is strongly recommended.
321        @param createParams If any parameters are required to create an instance,
322            they should be supplied here as name / value pairs. These do not need
323            to be set on the instance (handled elsewhere), just used if required
324            to differentiate which concrete class is created.
325
326                */
327                virtual Resource* createImpl(const String& name, ResourceHandle handle,
328                        const String& group, bool isManual, ManualResourceLoader* loader,
329            const NameValuePairList* createParams) = 0;
330                /** Add a newly created resource to the manager (note weak reference) */
331                virtual void addImpl( ResourcePtr& res );
332                /** Remove a resource from this manager; remove it from the lists. */
333                virtual void removeImpl( ResourcePtr& res );
334                /** Checks memory usage and pages out if required.
335                */
336                virtual void checkUsage(void);
337                /** Gets the current memory usage, in bytes. */
338                virtual size_t getMemoryUsage(void) const { return mMemoryUsage; }
339
340
341    public:
342                typedef HashMap< String, ResourcePtr > ResourceMap;
343                typedef std::map<ResourceHandle, ResourcePtr> ResourceHandleMap;
344    protected:
345        ResourceHandleMap mResourcesByHandle;
346        ResourceMap mResources;
347        ResourceHandle mNextHandle;
348        size_t mMemoryBudget; // In bytes
349        size_t mMemoryUsage; // In bytes
350
351                // IMPORTANT - all subclasses must populate the fields below
352
353                /// Patterns to use to look for scripts if supported (e.g. *.overlay)
354                StringVector mScriptPatterns;
355                /// Loading order relative to other managers, higher is later
356                Real mLoadOrder;
357                /// String identifying the resource type this manager handles
358                String mResourceType;
359
360    public:
361        typedef MapIterator<ResourceHandleMap> ResourceMapIterator;
362        /** Returns an iterator over all resources in this manager.
363        @note
364            Use of this iterator is NOT thread safe!
365        */
366        ResourceMapIterator getResourceIterator(void)
367        {
368            return ResourceMapIterator(mResourcesByHandle.begin(), mResourcesByHandle.end());
369        }
370
371   
372
373    };
374
375}
376
377#endif
Note: See TracBrowser for help on using the repository browser.