source: nrEngine/include/Resource.h @ 32

Revision 32, 9.1 KB checked in by art, 12 years ago (diff)
Line 
1/***************************************************************************
2 *                                                                         *
3 *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
4 *       mailto: <tevs@mpi-sb.mpg.de>                                      *
5 *                                                                         *
6 *   This program is free software; you can redistribute it and/or modify  *
7 *   it under the terms of the GNU General Public License as published by  *
8 *   the Free Software Foundation; either version 2 of the License, or     *
9 *   (at your option) any later version.                                   *
10 *                                                                         *
11 ***************************************************************************/
12
13
14#ifndef _NR_I_RESOURCE__H_
15#define _NR_I_RESOURCE__H_
16
17
18//----------------------------------------------------------------------------------
19// Includes
20//----------------------------------------------------------------------------------
21#include "Prerequisities.h"
22#include "ResourceSystem.h"
23#include <boost/enable_shared_from_this.hpp>
24
25namespace nrEngine{
26
27        //! General interface to hold any kind of resources
28        /**
29        * This is an interface which is describing how resource classes should looks like.
30        * Derive your own classes to get resource management system working. Each
31        * resource containing only once in the memory if it has the same name. So all
32        * names of resources should be unique. Resource is not directly stored by the
33        * manager but by the ResourceHolder. This holder just stores the resource
34        * and is unique for each resource. Manager just manages such holders and
35        * gives the resource pointers access to it.
36        *
37        * All derived classes must implement the behavior of resource objects correctly.
38        * Correct behavior of resource objects is done if resources do nothing what can
39        * change the empty resource behavior if they are empty. For example if you use texture
40        * and user is setting some values to it and it is at the moment unloaded, so the method
41        * will be called by the empty texture object. Empty texture object should stay empty and
42        * therefor there should not be any changes. So texture object has to check whenever it is
43        * an empty resource and should not do anything.
44        *
45        * The empty flag should be set by the loader, because only the loader does know
46        * if and when a resource can be defined as empty. For example you have to load the empty
47        * resource texture before you declare this resource as empty.
48        *
49        * \ingroup resource
50        **/
51        class _NRExport IResource : public boost::enable_shared_from_this<IResource>{
52        public:
53
54                /**
55                * Here the class should return cound of bytes reserved
56                * by the resource. The size must not contain the size of the class itself.
57                * For example: 32Bit Texture of 16x16 Pixel has the size: 16*16*4 = 1024 Bytes +
58                * some more bytes which does class need to store himself in the memory.
59                **/
60                NR_FORCEINLINE std::size_t getResDataSize(){return mResDataSize;}
61
62
63                /**
64                * Return here the name of the resource type. This name will be used
65                * to assign right empty resources to the resource pointer/holder objects.
66                * E.g: "Texture", "Sound",  ...
67                **/
68                NR_FORCEINLINE const std::string& getResType() const { return mResType; }
69
70
71                /**
72                * Return true if the resource is marked as loaded. If any resource is loaded
73                * so it contains in the memory and has it's full data there.
74                **/
75                NR_FORCEINLINE bool                     isResLoaded() const {return mResIsLoaded;}
76
77                /**
78                * Return handle of this resource
79                **/
80                NR_FORCEINLINE ResourceHandle           getResHandle() const {return mResHandle;}
81
82                /**
83                * Return group name to which one this resource belongs
84                **/
85                NR_FORCEINLINE const std::string&       getResGroup() const {return mResGroup;}
86
87                /**
88                * Get the name of the resource
89                **/
90                NR_FORCEINLINE const std::string&       getResName() const {return mResName;}
91
92                /**
93                * Get the file name from which one this resource can be restored or loaded
94                **/
95                NR_FORCEINLINE const std::list<std::string>&    getResFilenameList() const {return mResFileNames;}
96
97                /**
98                * Returns true if this resource is a empty resource. Empty resources are used
99                * to replace normal resources if they are unloaded.
100                **/
101                NR_FORCEINLINE bool                             isResEmpty()    {return mResIsEmpty;}
102
103        protected:
104               
105                /**
106                 * Create resource instance.
107                 **/
108                IResource(const std::string& resourceType);
109
110
111                /**
112                 * As soon as this destructor is called, the according loader will be
113                 * notified about removing the resource from the memory. So the loader
114                 * will correct it's database and notify also the ResourceManager about this
115                 * event.
116                 *
117                 * You have to call the unloadRes() method if you have some specific unloading
118                 * routines for your resource object. We can not call this from here, because
119                 * calling of virtual functions from constructor/destructor cause in
120                 * undefined behaviour. However we call the appropriate resource loader
121                 * to notify him that this resource is getting unloaded now.
122                 **/
123                virtual ~IResource();
124
125                /**
126                 * Unload the resource. Each resource should know how to unload it from
127                 * the memory. Unloading does not remove the resource it just unload used
128                 * data from memory. To remove the resource from memory you have either
129                 * to use ResourceManager or the ResourceLoader.
130                 *
131                 * Do here resource specific stuff. The method will be called by the loader,
132                 * so you do not have to notify the loader about this event.
133                 **/
134                virtual Result unloadRes();
135
136                /**
137                 * Reload resource. Each resource object should be able to reload itself
138                 * from the disk or other media. It can use the assigned loader to load files
139                 * or to make it by itself. At the end the resource should be marked as loaded.
140                 *
141                 * Do here resource specific stuff. The method will be called by the loader,
142                 * so you do not have to notify the loader about this event.
143                 **/
144                virtual Result reloadRes();
145               
146                /**
147                 * Loader will notify the resource that it has been restored.
148                 * A resource is restored if it was reloaded by the manager or
149                 * loader. The loader will restore the data in the way like it
150                 * has done when loading the resource. After that the loader will
151                 * notify the resource that it has been restored, so resource has
152                 * to do some initialization on this data if needed.
153                 *
154                 * The default behaviour on this function is just not to do anything.
155                 * So overload this method with your own, if you need any specific behaviour
156                 * on the restored data.
157                 **/
158                //virtual void notifyResReloaded() { }
159               
160                /**
161                 * Mark a resource as loaded. This method will not call the reloadRes()
162                 * method. Instead it will just mark this resource as it were loaded,
163                 * so you get access to real resource object through the pointers instead
164                 * of emtpy resource. Call this method if you create a resource by your
165                 * own without loading by loader.
166                 **/
167                NR_FORCEINLINE void markResLoaded() { mResIsLoaded = true; }
168               
169                /**
170                 * Add resource file name. The filename is used to associated the resource with.
171                 * If a resource is build upon of a multiple files, then all the files should
172                 * be added through this method.
173                 * @param filename Filename of a file associated with the resource
174                 **/
175                 void addResourceFilename(const std::string& filename);
176                 
177                 /**
178                  * @see addResourceFilename(const std::string& filename)
179                  * @param flist List of filenames to add
180                  **/
181                 void addResourceFilename(const std::list<std::string>& flist);
182                 
183        private:
184               
185                //! Only loader can change resource data
186                friend class IResourceLoader;
187
188                //! Also resource manager is a friend
189                friend class ResourceManager;
190
191                //! Shows whenever resource is loaded (is in the memory)
192                bool mResIsLoaded;
193
194                //! If true so this is a empty resource
195                bool mResIsEmpty;
196
197                //! Resource's loader with which one it was created
198                SharedPtr<IResourceLoader>      mResLoader;
199
200                //! Handle of the resource given from manager
201                ResourceHandle  mResHandle;
202
203                //! File associated with the resource
204                std::list<std::string>  mResFileNames;
205
206                //! Count of bytes that this resource is occupies in the memory
207                std::size_t     mResDataSize;
208
209                //! Name of the resource type
210                std::string     mResType;
211               
212                //! Group name to which one this resource own
213                std::string mResGroup;
214
215                //! Name of the resource
216                std::string mResName;
217               
218                /**
219                 * Set the resource type for this resource.
220                 * Method is declared as protected, so only engine can do this.
221                 *
222                 * @param type Name of the resource type
223                 **/
224                NR_FORCEINLINE void     setResourceType(const std::string& type) { mResType = type; }
225
226                /**
227                 * If the unloading of resource is done through the resource manager,
228                 * so this method will be called.
229                 **/
230                Result unloadResThroughLoader();
231               
232                /**
233                 * Reload the resource through the according resource loader.
234                 **/
235                Result reloadResThroughLoader();
236
237                /**
238                 * Remove the resource through it's loader
239                 **/
240                Result removeResThroughLoader();
241
242                /**
243                * Get shared pointer from this class
244                **/     
245                SharedPtr<IResource> getSharedPtrFromThis()
246                {
247                        return shared_from_this();
248                }
249               
250                class _deleter{
251                public:
252                        void operator()(IResource* p) { delete p; }
253                };
254        };
255
256};
257
258#endif
Note: See TracBrowser for help on using the repository browser.