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

Revision 1809, 40.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#ifndef _ResourceGroupManager_H__
26#define _ResourceGroupManager_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreSingleton.h"
30#include "OgreCommon.h"
31#include "OgreDataStream.h"
32#include "OgreResource.h"
33#include "OgreArchive.h"
34
35namespace Ogre {
36
37    /** This abstract class defines an interface which is called back during
38        resource group loading to indicate the progress of the load.
39        @remarks
40                Resource group loading is in 2 phases - creating resources from
41                declarations (which includes parsing scripts), and loading
42                resources. Note that you don't necessarily have to have both; it
43                is quite possible to just parse all the scripts for a group (see
44                ResourceGroupManager::initialiseResourceGroup, but not to
45                load the resource group.
46                The sequence of events is (* signifies a repeating item):
47                <ul>
48                <li>resourceGroupScriptingStarted</li>
49                <li>scriptParseStarted (*)</li>
50        <li>scriptParseEnded (*)</li>
51                <li>resourceGroupScriptingEnded</li>
52                <li>resourceGroupLoadStarted</li>
53                <li>resourceLoadStarted (*)</li>
54        <li>resourceLoadEnded (*)</li>
55        <li>worldGeometryStageStarted (*)</li>
56        <li>worldGeometryStageEnded (*)</li>
57                <li>resourceGroupLoadEnded</li>
58                </ul>
59    @note
60        If OGRE_THREAD_SUPPORT is 1, this class is thread-safe.
61
62    */
63    class _OgreExport ResourceGroupListener
64    {
65    public:
66        virtual ~ResourceGroupListener() {}
67
68                /** This event is fired when a resource group begins parsing scripts.
69                @param groupName The name of the group
70                @param scriptCount The number of scripts which will be parsed
71                */
72                virtual void resourceGroupScriptingStarted(const String& groupName, size_t scriptCount) = 0;
73                /** This event is fired when a script is about to be parsed.
74                @param scriptName Name of the to be parsed
75                */
76                virtual void scriptParseStarted(const String& scriptName) = 0;
77                /** This event is fired when the script has been fully parsed.
78                */
79                virtual void scriptParseEnded(void) = 0;
80                /** This event is fired when a resource group finished parsing scripts. */
81                virtual void resourceGroupScriptingEnded(const String& groupName) = 0;
82
83                /** This event is fired  when a resource group begins loading.
84                @param groupName The name of the group being loaded
85                @param resourceCount The number of resources which will be loaded, including
86            a number of stages required to load any linked world geometry
87                */
88                virtual void resourceGroupLoadStarted(const String& groupName, size_t resourceCount) = 0;
89                /** This event is fired when a declared resource is about to be loaded.
90                @param resource Weak reference to the resource loaded.
91                */
92                virtual void resourceLoadStarted(const ResourcePtr& resource) = 0;
93        /** This event is fired when the resource has been loaded.
94        */
95        virtual void resourceLoadEnded(void) = 0;
96        /** This event is fired when a stage of loading linked world geometry
97            is about to start. The number of stages required will have been
98            included in the resourceCount passed in resourceGroupLoadStarted.
99        @param description Text description of what was just loaded
100        */
101        virtual void worldGeometryStageStarted(const String& description) = 0;
102        /** This event is fired when a stage of loading linked world geometry
103            has been completed. The number of stages required will have been
104            included in the resourceCount passed in resourceGroupLoadStarted.
105        @param description Text description of what was just loaded
106        */
107        virtual void worldGeometryStageEnded(void) = 0;
108
109                /** This event is fired when a resource group finished loading. */
110                virtual void resourceGroupLoadEnded(const String& groupName) = 0;
111
112    };
113    /** This singleton class manages the list of resource groups, and notifying
114        the various resource managers of their obligations to load / unload
115        resources in a group. It also provides facilities to monitor resource
116        loading per group (to do progress bars etc), provided the resources
117        that are required are pre-registered.
118    @par
119        Defining new resource groups,  and declaring the resources you intend to
120        use in advance is optional, however it is a very useful feature. In addition,
121                if a ResourceManager supports the definition of resources through scripts,
122                then this is the class which drives the locating of the scripts and telling
123                the ResourceManager to parse them.
124        @par
125                There are several states that a resource can be in (the concept, not the
126                object instance in this case):
127                <ol>
128                <li><b>Undefined</b>. Nobody knows about this resource yet. It might be
129                in the filesystem, but Ogre is oblivious to it at the moment - there
130                is no Resource instance. This might be because it's never been declared
131                (either in a script, or using ResourceGroupManager::declareResource), or
132                it may have previously been a valid Resource instance but has been
133                removed, either individually through ResourceManager::remove or as a group
134                through ResourceGroupManager::clearResourceGroup.</li>
135                <li><b>Declared</b>. Ogre has some forewarning of this resource, either
136                through calling ResourceGroupManager::declareResource, or by declaring
137                the resource in a script file which is on one of the resource locations
138                which has been defined for a group. There is still no instance of Resource,
139                but Ogre will know to create this resource when
140                ResourceGroupManager::initialiseResourceGroup is called (which is automatic
141                if you declare the resource group before Root::initialise).</li>
142                <li><b>Unloaded</b>. There is now a Resource instance for this resource,
143                although it is not loaded. This means that code which looks for this
144                named resource will find it, but the Resource is not using a lot of memory
145                because it is in an unloaded state. A Resource can get into this state
146                by having just been created by ResourceGroupManager::initialiseResourceGroup
147                (either from a script, or from a call to declareResource), by
148                being created directly from code (ResourceManager::create), or it may
149                have previously been loaded and has been unloaded, either individually
150                through Resource::unload, or as a group through ResourceGroupManager::unloadResourceGroup.</li>
151                <li><b>Loaded</b>The Resource instance is fully loaded. This may have
152                happened implicitly because something used it, or it may have been
153                loaded as part of a group.</li>
154                </ol>
155                @see ResourceGroupManager::declareResource
156                @see ResourceGroupManager::initialiseResourceGroup
157                @see ResourceGroupManager::loadResourceGroup
158                @see ResourceGroupManager::unloadResourceGroup
159                @see ResourceGroupManager::clearResourceGroup
160    */
161    class _OgreExport ResourceGroupManager : public Singleton<ResourceGroupManager>
162    {
163    public:
164                OGRE_AUTO_MUTEX // public to allow external locking
165                /// Default resource group name
166                static String DEFAULT_RESOURCE_GROUP_NAME;
167        /// Internal resource group name (should be used by OGRE internal only)
168        static String INTERNAL_RESOURCE_GROUP_NAME;
169                /// Bootstrap resource group name (min OGRE resources)
170                static String BOOTSTRAP_RESOURCE_GROUP_NAME;
171                /// Special resource group name which causes resource group to be automatically determined based on searching for the resource in all groups.
172                static String AUTODETECT_RESOURCE_GROUP_NAME;
173                /// The number of reference counts held per resource by the resource system
174                static size_t RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS;
175        /// Nested struct defining a resource declaration
176        struct ResourceDeclaration
177        {
178            String resourceName;
179            String resourceType;
180            ManualResourceLoader* loader;
181                        NameValuePairList parameters;
182        };
183        /// List of resource declarations
184        typedef std::list<ResourceDeclaration> ResourceDeclarationList;
185    protected:
186                /// Map of resource types (strings) to ResourceManagers, used to notify them to load / unload group contents
187                typedef std::map<String, ResourceManager*> ResourceManagerMap;
188        ResourceManagerMap mResourceManagerMap;
189
190                /// Map of loading order (Real) to ScriptLoader, used to order script parsing
191                typedef std::multimap<Real, ScriptLoader*> ScriptLoaderOrderMap;
192                ScriptLoaderOrderMap mScriptLoaderOrderMap;
193
194                typedef std::vector<ResourceGroupListener*> ResourceGroupListenerList;
195        ResourceGroupListenerList mResourceGroupListenerList;
196
197        /// Resource index entry, resourcename->location
198        typedef std::map<String, Archive*> ResourceLocationIndex;
199
200                /// Resource location entry
201                struct ResourceLocation
202                {
203                        /// Pointer to the archive which is the destination
204                        Archive* archive;
205                        /// Whether this location was added recursively
206                        bool recursive;
207                };
208                /// List of possible file locations
209                typedef std::list<ResourceLocation*> LocationList;
210                /// List of resources which can be loaded / unloaded
211                typedef std::list<ResourcePtr> LoadUnloadResourceList;
212                /// Resource group entry
213                struct ResourceGroup
214                {
215                        OGRE_AUTO_MUTEX
216                        /// Group name
217                        String name;
218                        /// Whether group has been initialised
219                        bool initialised;
220                        /// List of possible locations to search
221                        LocationList locationList;
222                        /// Index of resource names to locations, built for speedy access (case sensitive archives)
223                        ResourceLocationIndex resourceIndexCaseSensitive;
224            /// Index of resource names to locations, built for speedy access (case insensitive archives)
225            ResourceLocationIndex resourceIndexCaseInsensitive;
226                        /// Pre-declared resources, ready to be created
227                        ResourceDeclarationList resourceDeclarations;
228                        /// Created resources which are ready to be loaded / unloaded
229                        // Group by loading order of the type (defined by ResourceManager)
230                        // (e.g. skeletons and materials before meshes)
231                        typedef std::map<Real, LoadUnloadResourceList*> LoadResourceOrderMap;
232                        LoadResourceOrderMap loadResourceOrderMap;
233            /// Linked world geometry, as passed to setWorldGeometry
234            String worldGeometry;
235            /// Scene manager to use with linked world geometry
236            SceneManager* worldGeometrySceneManager;
237                };
238        /// Map from resource group names to groups
239        typedef std::map<String, ResourceGroup*> ResourceGroupMap;
240        ResourceGroupMap mResourceGroupMap;
241
242        /// Group name for world resources
243        String mWorldGroupName;
244
245                /** Parses all the available scripts found in the resource locations
246                for the given group, for all ResourceManagers.
247                @remarks
248                        Called as part of initialiseResourceGroup
249                */
250                void parseResourceGroupScripts(ResourceGroup* grp);
251                /** Create all the pre-declared resources.
252                @remarks
253                        Called as part of initialiseResourceGroup
254                */
255                void createDeclaredResources(ResourceGroup* grp);
256                /** Adds a created resource to a group. */
257                void addCreatedResource(ResourcePtr& res, ResourceGroup& group);
258                /** Get resource group */
259                ResourceGroup* getResourceGroup(const String& name);
260                /** Drops contents of a group, leave group there, notify ResourceManagers. */
261                void dropGroupContents(ResourceGroup* grp);
262                /** Delete a group for shutdown - don't notify ResourceManagers. */
263                void deleteGroup(ResourceGroup* grp);
264                /// Internal find method for auto groups
265                ResourceGroup* findGroupContainingResourceImpl(const String& filename);
266                /// Internal event firing method
267                void fireResourceGroupScriptingStarted(const String& groupName, size_t scriptCount);
268                /// Internal event firing method
269                void fireScriptStarted(const String& scriptName);
270        /// Internal event firing method
271        void fireScriptEnded(void);
272                /// Internal event firing method
273                void fireResourceGroupScriptingEnded(const String& groupName);
274                /// Internal event firing method
275                void fireResourceGroupLoadStarted(const String& groupName, size_t resourceCount);
276        /// Internal event firing method
277        void fireResourceStarted(const ResourcePtr& resource);
278                /// Internal event firing method
279                void fireResourceEnded(void);
280                /// Internal event firing method
281                void fireResourceGroupLoadEnded(const String& groupName);
282
283
284
285                /// Stored current group - optimisation for when bulk loading a group
286                ResourceGroup* mCurrentGroup;
287    public:
288        ResourceGroupManager();
289        virtual ~ResourceGroupManager();
290
291        /** Create a resource group.
292        @remarks
293            A resource group allows you to define a set of resources that can
294            be loaded / unloaded as a unit. For example, it might be all the
295            resources used for the level of a game. There is always one predefined
296            resource group called ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
297                        which is typically used to hold all resources which do not need to
298                        be unloaded until shutdown. There is another predefined resource
299            group called ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME too,
300            which should be used by OGRE internal only, the resources created
301            in this group aren't supposed to modify, unload or remove by user.
302            You can create additional ones so that you can control the life of
303            your resources in whichever way you wish.
304                        There is one other predefined value,
305                        ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME; using this
306                        causes the group name to be derived at load time by searching for
307                        the resource in the resource locations of each group in turn.
308        @par
309            Once you have defined a resource group, resources which will be loaded
310                        as part of it are defined in one of 3 ways:
311                        <ol>
312                        <li>Manually through declareResource(); this is useful for scripted
313                                declarations since it is entirely generalised, and does not
314                                create Resource instances right away</li>
315                        <li>Through the use of scripts; some ResourceManager subtypes have
316                                script formats (e.g. .material, .overlay) which can be used
317                                to declare resources</li>
318                        <li>By calling ResourceManager::create to create a resource manually.
319                        This resource will go on the list for it's group and will be loaded
320                        and unloaded with that group</li>
321                        </ol>
322                        You must remember to call initialiseResourceGroup if you intend to use
323                        the first 2 types.
324        @param name The name to give the resource group.
325        */
326        void createResourceGroup(const String& name);
327
328
329        /** Initialises a resource group.
330                @remarks
331                        After creating a resource group, adding some resource locations, and
332                        perhaps pre-declaring some resources using declareResource(), but
333                        before you need to use the resources in the group, you
334                        should call this method to initialise the group. By calling this,
335                        you are triggering the following processes:
336                        <ol>
337                        <li>Scripts for all resource types which support scripting are
338                                parsed from the resource locations, and resources within them are
339                                created (but not loaded yet).</li>
340                        <li>Creates all the resources which have just pre-declared using
341                        declareResource (again, these are not loaded yet)</li>
342                        </ol>
343                        So what this essentially does is create a bunch of unloaded Resource entries
344                        in the respective ResourceManagers based on scripts, and resources
345                        you've pre-declared. That means that code looking for these resources
346                        will find them, but they won't be taking up much memory yet, until
347                        they are either used, or they are loaded in bulk using loadResourceGroup.
348                        Loading the resource group in bulk is entirely optional, but has the
349                        advantage of coming with progress reporting as resources are loaded.
350                @par
351                        Failure to call this method means that loadResourceGroup will do
352                        nothing, and any resources you define in scripts will not be found.
353                        Similarly, once you have called this method you won't be able to
354                        pick up any new scripts or pre-declared resources, unless you
355                        call clearResourceGroup, set up declared resources, and call this
356                        method again.
357                @note
358                        When you call Root::initialise, all resource groups that have already been
359                        created are automatically initialised too. Therefore you do not need to
360                        call this method for groups you define and set up before you call
361                        Root::initialise. However, since one of the most useful features of
362                        resource groups is to set them up after the main system initialisation
363                        has occurred (e.g. a group per game level), you must remember to call this
364                        method for the groups you create after this.
365
366                @param name The name of the resource group to initialise
367                */
368                void initialiseResourceGroup(const String& name);
369
370                /** Initialise all resource groups which are yet to be initialised.
371                @see ResourceGroupManager::intialiseResourceGroup
372                */
373                void initialiseAllResourceGroups(void);
374
375                /** Loads a resource group.
376        @remarks
377                        Loads any created resources which are part of the named group.
378                        Note that resources must have already been created by calling
379                        ResourceManager::create, or declared using declareResource() or
380                        in a script (such as .material and .overlay). The latter requires
381                        that initialiseResourceGroup has been called.
382               
383                        When this method is called, this class will callback any ResourceGroupListeners
384                        which have been registered to update them on progress.
385        @param name The name to of the resource group to load.
386                @param loadMainResources If true, loads normal resources associated
387                        with the group (you might want to set this to false if you wanted
388                        to just load world geometry in bulk)
389                @param loadWorldGeom If true, loads any linked world geometry
390                        @see ResourceGroupManager::linkWorldGeometryToResourceGroup
391        */
392        void loadResourceGroup(const String& name, bool loadMainResources = true,
393                        bool loadWorldGeom = true);
394
395        /** Unloads a resource group.
396        @remarks
397            This method unloads all the resources that have been declared as
398            being part of the named resource group. Note that these resources
399            will still exist in their respective ResourceManager classes, but
400            will be in an unloaded state. If you want to remove them entirely,
401            you should use clearResourceGroup or destroyResourceGroup.
402        @param name The name to of the resource group to unload.
403        @param reloadableOnly If set to true, only unload the resource that is
404            reloadable. Because some resources isn't reloadable, they will be
405            unloaded but can't load them later. Thus, you might not want to them
406            unloaded. Or, you might unload all of them, and then populate them
407            manually later.
408            @see Resource::isReloadable for resource is reloadable.
409        */
410        void unloadResourceGroup(const String& name, bool reloadableOnly = true);
411
412                /** Unload all resources which are not referenced by any other object.
413                @remarks
414                        This method behaves like unloadResourceGroup, except that it only
415                        unloads resources in the group which are not in use, ie not referenced
416                        by other objects. This allows you to free up some memory selectively
417                        whilst still keeping the group around (and the resources present,
418                        just not using much memory).
419                @param name The name of the group to check for unreferenced resources
420                @param reloadableOnly If true (the default), only unloads resources
421                        which can be subsequently automatically reloaded
422                */
423                void unloadUnreferencedResourcesInGroup(const String& name,
424                        bool reloadableOnly = true);
425
426                /** Clears a resource group.
427                @remarks
428                        This method unloads all resources in the group, but in addition it
429                        removes all those resources from their ResourceManagers, and then
430                        clears all the members from the list. That means after calling this
431                        method, there are no resources declared as part of the named group
432                        any more. Resource locations still persist though.
433        @param name The name to of the resource group to clear.
434                */
435                void clearResourceGroup(const String& name);
436       
437        /** Destroys a resource group, clearing it first, destroying the resources
438            which are part of it, and then removing it from
439            the list of resource groups.
440        @param name The name of the resource group to destroy.
441        */
442        void destroyResourceGroup(const String& name);
443
444        /** Method to add a resource location to for a given resource group.
445        @remarks
446            Resource locations are places which are searched to load resource files.
447            When you choose to load a file, or to search for valid files to load,
448            the resource locations are used.
449        @param name The name of the resource location; probably a directory, zip file, URL etc.
450        @param locType The codename for the resource type, which must correspond to the
451            Archive factory which is providing the implementation.
452        @param resGroup The name of the resource group for which this location is
453            to apply. ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME is the
454                        default group which always exists, and can
455            be used for resources which are unlikely to be unloaded until application
456            shutdown. Otherwise it must be the name of a group; if it
457            has not already been created with createResourceGroup then it is created
458            automatically.
459        @param recursive Whether subdirectories will be searched for files when using
460                        a pattern match (such as *.material), and whether subdirectories will be
461                        indexed. This can slow down initial loading of the archive and searches.
462                        When opening a resource you still need to use the fully qualified name,
463                        this allows duplicate names in alternate paths.
464        */
465        void addResourceLocation(const String& name, const String& locType,
466            const String& resGroup = DEFAULT_RESOURCE_GROUP_NAME, bool recursive = false);
467        /** Removes a resource location from the search path. */
468        void removeResourceLocation(const String& name,
469                        const String& resGroup = DEFAULT_RESOURCE_GROUP_NAME);
470
471        /** Declares a resource to be a part of a resource group, allowing you
472            to load and unload it as part of the group.
473        @remarks
474            By declaring resources before you attempt to use them, you can
475            more easily control the loading and unloading of those resources
476            by their group. Declaring them also allows them to be enumerated,
477            which means events can be raised to indicate the loading progress
478            (@see ResourceGroupListener). Note that another way of declaring
479                        resources is to use a script specific to the resource type, if
480                        available (e.g. .material).
481                @par
482                        Declared resources are not created as Resource instances (and thus
483                        are not available through their ResourceManager) until initialiseResourceGroup
484                        is called, at which point all declared resources will become created
485                        (but unloaded) Resource instances, along with any resources declared
486                        in scripts in resource locations associated with the group.
487        @param name The resource name.
488        @param resourceType The type of the resource. Ogre comes preconfigured with
489            a number of resource types:
490            <ul>
491            <li>Font</li>
492            <li>GpuProgram</li>
493            <li>HighLevelGpuProgram</li>
494            <li>Material</li>
495            <li>Mesh</li>
496            <li>Skeleton</li>
497            <li>Texture</li>
498            </ul>
499            .. but more can be added by plugin ResourceManager classes.
500        @param groupName The name of the group to which it will belong.
501                @param loadParameters A list of name / value pairs which supply custom
502                        parameters to the resource which will be required before it can
503                        be loaded. These are specific to the resource type.
504        */
505        void declareResource(const String& name, const String& resourceType,
506            const String& groupName = DEFAULT_RESOURCE_GROUP_NAME,
507                        const NameValuePairList& loadParameters = NameValuePairList());
508        /** Declares a resource to be a part of a resource group, allowing you
509            to load and unload it as part of the group.
510        @remarks
511            By declaring resources before you attempt to use them, you can
512            more easily control the loading and unloading of those resources
513            by their group. Declaring them also allows them to be enumerated,
514            which means events can be raised to indicate the loading progress
515            (@see ResourceGroupListener). Note that another way of declaring
516            resources is to use a script specific to the resource type, if
517            available (e.g. .material).
518        @par
519            Declared resources are not created as Resource instances (and thus
520            are not available through their ResourceManager) until initialiseResourceGroup
521            is called, at which point all declared resources will become created
522            (but unloaded) Resource instances, along with any resources declared
523            in scripts in resource locations associated with the group.
524        @param name The resource name.
525        @param resourceType The type of the resource. Ogre comes preconfigured with
526            a number of resource types:
527            <ul>
528            <li>Font</li>
529            <li>GpuProgram</li>
530            <li>HighLevelGpuProgram</li>
531            <li>Material</li>
532            <li>Mesh</li>
533            <li>Skeleton</li>
534            <li>Texture</li>
535            </ul>
536            .. but more can be added by plugin ResourceManager classes.
537        @param groupName The name of the group to which it will belong.
538        @param loader Pointer to a ManualResourceLoader implementation which will
539            be called when the Resource wishes to load. If supplied, the resource
540            is manually loaded, otherwise it'll loading from file automatic.
541            @note We don't support declare manually loaded resource without loader
542                here, since it's meaningless.
543        @param loadParameters A list of name / value pairs which supply custom
544            parameters to the resource which will be required before it can
545            be loaded. These are specific to the resource type.
546        */
547        void declareResource(const String& name, const String& resourceType,
548            const String& groupName, ManualResourceLoader* loader,
549            const NameValuePairList& loadParameters = NameValuePairList());
550        /** Undeclare a resource.
551                @remarks
552                        Note that this will not cause it to be unloaded
553            if it is already loaded, nor will it destroy a resource which has
554                        already been created if initialiseResourceGroup has been called already.
555                        Only unloadResourceGroup / clearResourceGroup / destroyResourceGroup
556                        will do that.
557        @param name The name of the resource.
558                @param groupName The name of the group this resource was declared in.
559        */
560        void undeclareResource(const String& name, const String& groupName);
561
562                /** Open a single resource by name and return a DataStream
563                        pointing at the source of the data.
564                @param resourceName The name of the resource to locate.
565                        Even if resource locations are added recursively, you
566                        must provide a fully qualified name to this method. You
567                        can find out the matching fully qualified names by using the
568                        find() method if you need to.
569                @param groupName The name of the resource group; this determines which
570                        locations are searched.
571                @param searchGroupsIfNotFound If true, if the resource is not found in
572                        the group specified, other groups will be searched. If you're
573                        loading a real Resource using this option, you <strong>must</strong>
574                        also provide the resourceBeingLoaded parameter to enable the
575                        group membership to be changed
576                @param resourceBeingLoaded Optional pointer to the resource being
577                        loaded, which you should supply if you want
578                @returns Shared pointer to data stream containing the data, will be
579                        destroyed automatically when no longer referenced
580                */
581                DataStreamPtr openResource(const String& resourceName,
582                        const String& groupName = DEFAULT_RESOURCE_GROUP_NAME,
583                        bool searchGroupsIfNotFound = true, Resource* resourceBeingLoaded = 0);
584
585                /** Open all resources matching a given pattern (which can contain
586                        the character '*' as a wildcard), and return a collection of
587                        DataStream objects on them.
588                @param pattern The pattern to look for. If resource locations have been
589                        added recursively, subdirectories will be searched too so this
590                        does not need to be fully qualified.
591                @param groupName The resource group; this determines which locations
592                        are searched.
593                @returns Shared pointer to a data stream list , will be
594                        destroyed automatically when no longer referenced
595                */
596                DataStreamListPtr openResources(const String& pattern,
597                        const String& groupName = DEFAULT_RESOURCE_GROUP_NAME);
598               
599        /** List all file names in a resource group.
600        @note
601        This method only returns filenames, you can also retrieve other
602        information using listFileInfo.
603        @param groupName The name of the group
604        @returns A list of filenames matching the criteria, all are fully qualified
605        */
606        StringVectorPtr listResourceNames(const String& groupName);
607
608        /** List all files in a resource group with accompanying information.
609        @param groupName The name of the group
610        @returns A list of structures detailing quite a lot of information about
611        all the files in the archive.
612        */
613        FileInfoListPtr listResourceFileInfo(const String& groupName);
614
615        /** Find all file names matching a given pattern in a resource group.
616        @note
617        This method only returns filenames, you can also retrieve other
618        information using findFileInfo.
619        @param groupName The name of the group
620        @param pattern The pattern to search for; wildcards (*) are allowed
621        @returns A list of filenames matching the criteria, all are fully qualified
622        */
623        StringVectorPtr findResourceNames(const String& groupName, const String& pattern);
624
625        /** Find out if the named file exists in a group.
626        @param group The name of the resource group
627        @param filename Fully qualified name of the file to test for
628        */
629        bool resourceExists(const String& group, const String& filename);
630
631        /** Find out if the named file exists in a group.
632        @param group Pointer to the resource group
633        @param filename Fully qualified name of the file to test for
634        */
635        bool resourceExists(ResourceGroup* group, const String& filename);
636                /** Find the group in which a resource exists.
637                @param filename Fully qualified name of the file the resource should be
638                        found as
639                @returns Name of the resource group the resource was found in. An
640                        exception is thrown if the group could not be determined.
641                */
642                const String& findGroupContainingResource(const String& filename);
643
644        /** Find all files matching a given pattern in a group and get
645        some detailed information about them.
646        @param group The name of the resource group
647        @param pattern The pattern to search for; wildcards (*) are allowed
648        @returns A list of file information structures for all files matching
649        the criteria.
650        */
651        FileInfoListPtr findResourceFileInfo(const String& group, const String& pattern);
652
653       
654        /** Adds a ResourceGroupListener which will be called back during
655            resource loading events.
656        */
657        void addResourceGroupListener(ResourceGroupListener* l);
658        /** Removes a ResourceGroupListener */
659        void removeResourceGroupListener(ResourceGroupListener* l);
660
661        /** Sets the resource group that 'world' resources will use.
662        @remarks
663            This is the group which should be used by SceneManagers implementing
664            world geometry when looking for their resources. Defaults to the
665            DEFAULT_RESOURCE_GROUP_NAME but this can be altered.
666        */
667        void setWorldResourceGroupName(const String& groupName) {mWorldGroupName = groupName;}
668
669        /// Sets the resource group that 'world' resources will use.
670        const String& getWorldResourceGroupName(void) const { return mWorldGroupName; }
671
672        /** Associates some world geometry with a resource group, causing it to
673            be loaded / unloaded with the resource group.
674        @remarks
675            You would use this method to essentially defer a call to
676            SceneManager::setWorldGeometry to the time when the resource group
677            is loaded. The advantage of this is that compatible scene managers
678            will include the estimate of the number of loading stages for that
679            world geometry when the resource group begins loading, allowing you
680            to include that in a loading progress report.
681        @param group The name of the resource group
682        @param worldGeometry The parameter which should be passed to setWorldGeometry
683        @param sceneManager The SceneManager which should be called
684        */
685        void linkWorldGeometryToResourceGroup(const String& group,
686            const String& worldGeometry, SceneManager* sceneManager);
687
688        /** Clear any link to world geometry from a resource group.
689        @remarks
690            Basically undoes a previous call to linkWorldGeometryToResourceGroup.
691        */
692        void unlinkWorldGeometryFromResourceGroup(const String& group);
693
694        /** Shutdown all ResourceManagers, performed as part of clean-up. */
695        void shutdownAll(void);
696
697
698        /** Internal method for registering a ResourceManager (which should be
699            a singleton). Creators of plugins can register new ResourceManagers
700            this way if they wish.
701                @remarks
702                        ResourceManagers that wish to parse scripts must also call
703                        _registerScriptLoader.
704        @param resourceType String identifying the resource type, must be unique.
705        @param rm Pointer to the ResourceManager instance.
706        */
707        void _registerResourceManager(const String& resourceType, ResourceManager* rm);
708
709        /** Internal method for unregistering a ResourceManager.
710                @remarks
711                        ResourceManagers that wish to parse scripts must also call
712                        _unregisterScriptLoader.
713        @param resourceType String identifying the resource type.
714        */
715        void _unregisterResourceManager(const String& resourceType);
716
717
718        /** Internal method for registering a ScriptLoader.
719                @remarks ScriptLoaders parse scripts when resource groups are initialised.
720        @param su Pointer to the ScriptLoader instance.
721        */
722        void _registerScriptLoader(ScriptLoader* su);
723
724        /** Internal method for unregistering a ScriptLoader.
725        @param su Pointer to the ScriptLoader instance.
726        */
727        void _unregisterScriptLoader(ScriptLoader* su);
728
729                /** Internal method for getting a registered ResourceManager.
730                @param resourceType String identifying the resource type.
731                */
732                ResourceManager* _getResourceManager(const String& resourceType);
733
734                /** Internal method called by ResourceManager when a resource is created.
735                @param res Weak reference to resource
736                */
737                void _notifyResourceCreated(ResourcePtr& res);
738
739                /** Internal method called by ResourceManager when a resource is removed.
740                @param res Weak reference to resource
741                */
742                void _notifyResourceRemoved(ResourcePtr& res);
743
744                /** Internale method to notify the group manager that a resource has
745                        changed group (only applicable for autodetect group) */
746                void _notifyResourceGroupChanged(const String& oldGroup, Resource* res);
747
748                /** Internal method called by ResourceManager when all resources
749                        for that manager are removed.
750                @param manager Pointer to the manager for which all resources are being removed
751                */
752                void _notifyAllResourcesRemoved(ResourceManager* manager);
753
754        /** Notify this manager that one stage of world geometry loading has been
755            started.
756        @remarks
757            Custom SceneManagers which load custom world geometry should call this
758            method the number of times equal to the value they return from
759            SceneManager::estimateWorldGeometry while loading their geometry.
760        */
761        void _notifyWorldGeometryStageStarted(const String& description);
762        /** Notify this manager that one stage of world geometry loading has been
763            completed.
764        @remarks
765            Custom SceneManagers which load custom world geometry should call this
766            method the number of times equal to the value they return from
767            SceneManager::estimateWorldGeometry while loading their geometry.
768        */
769        void _notifyWorldGeometryStageEnded(void);
770
771                /** Get a list of the currently defined resource groups.
772                @note This method intentionally returns a copy rather than a reference in
773                        order to avoid any contention issues in multithreaded applications.
774                @returns A copy of list of currently defined groups.
775                */
776                StringVector getResourceGroups(void);
777                /** Get the list of resource declarations for the specified group name.
778                @note This method intentionally returns a copy rather than a reference in
779                        order to avoid any contention issues in multithreaded applications.
780                @param groupName The name of the group
781                @returns A copy of list of currently defined resources.
782                */
783                ResourceDeclarationList getResourceDeclarationList(const String& groupName);
784
785                /** Override standard Singleton retrieval.
786        @remarks
787        Why do we do this? Well, it's because the Singleton
788        implementation is in a .h file, which means it gets compiled
789        into anybody who includes it. This is needed for the
790        Singleton template to work, but we actually only want it
791        compiled into the implementation of the class based on the
792        Singleton, not all of them. If we don't change this, we get
793        link errors when trying to use the Singleton-based class from
794        an outside dll.
795        @par
796        This method just delegates to the template version anyway,
797        but the implementation stays in this single compilation unit,
798        preventing link errors.
799        */
800        static ResourceGroupManager& getSingleton(void);
801        /** Override standard Singleton retrieval.
802        @remarks
803        Why do we do this? Well, it's because the Singleton
804        implementation is in a .h file, which means it gets compiled
805        into anybody who includes it. This is needed for the
806        Singleton template to work, but we actually only want it
807        compiled into the implementation of the class based on the
808        Singleton, not all of them. If we don't change this, we get
809        link errors when trying to use the Singleton-based class from
810        an outside dll.
811        @par
812        This method just delegates to the template version anyway,
813        but the implementation stays in this single compilation unit,
814        preventing link errors.
815        */
816        static ResourceGroupManager* getSingletonPtr(void);
817
818    };
819}
820
821#endif
Note: See TracBrowser for help on using the repository browser.