source: nrEngine/include/ResourceHolder.h @ 1

Revision 1, 6.3 KB checked in by art, 14 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_RESOURCE_HOLDER_H_
15#define _NR_RESOURCE_HOLDER_H_
16
17
18//----------------------------------------------------------------------------------
19// Includes
20//----------------------------------------------------------------------------------
21#include "Prerequisities.h"
22
23namespace nrEngine{
24       
25        /**
26        * This constant defines the size of the lock stack.
27        * All locking states are stored in the stack, to allow nested lock/unlock calling.
28        * \ingroup resource
29        **/
30        const int32 NR_RESOURCE_LOCK_STACK = 128;
31
32        /// @cond SHOW_RESOURCE_HOLDER
33       
34        //! Interstage between manager and resources for more efficience and safety
35        /**
36        * This is a holder class which is holding a resource of different type.
37        * Resource pointers are pointing to this holder, so by referencing the pointer
38        * you do not have to ask the manager to get the resource, but directly to access
39        * it through this holder. So actually resource manager manages holders and
40        * not resources or pointers directly.
41        *
42        * We use such a system to be more efficient by dereferncing the resource pointer.
43        * Other and more trivial way is to ask the manager for resource by giving him the
44        * handle. This end in a look up of handle tables and returning the resource pointer.
45        * If we use holders, pointers will directly access that holders and each holder
46        * is showing to one resource. So we do not have to do any lookups.
47        *
48        * This class is working transparent to the whole resource management system, so
49        * you actually do not have to know how this class works and you also do not have
50        * to derive any classes from it.
51        *
52        * This system was get from Game Programming Gems 4, and was expanded to be more
53        * flexible and more efficient.
54        *
55        * \ingroup resource
56        */
57        class _NRExport ResourceHolder{
58                public:
59                                       
60                        /**
61                        * Remove the object from the memory and also delete the resource
62                        * which is holded by this holder. The destructor should be declared as
63                        * public so it can be used by smart pointers
64                        **/
65                        ~ResourceHolder();
66
67                private:
68
69                        friend class IResourceLoader;
70                        friend class IResourcePtr;
71                        friend class ResourceManager;
72                       
73                        /**
74                        * Create the object of this class
75                        **/
76                        ResourceHolder(IResource* res, IResource* empty);
77               
78                        //! pointer that holds the resource
79                        IResource* mResource;
80                       
81                        //! pointer that holds the empty resource object
82                        IResource* mEmptyResource;
83                       
84                        //! Store number that represents how often the resource was in use
85                        uint32          countAccess;
86                       
87                        //! Store the status if real resources lock stack
88                        bool            mLockStack[NR_RESOURCE_LOCK_STACK];
89                       
90                        //! Current position in the stack
91                        int32           mLockStackTop;
92                       
93                        /**
94                        * Lock real resource for using. Locking has the effect that the getResource() method
95                        * will now return real resources also if it is unloaded.
96                        *
97                        * @return true if locking was successfull otherwise false
98                        * @note If the lock stack is full you are not able lock anymore
99                        **/
100                        bool lockPure();
101                       
102                        /**
103                        * Unlock the real resurce. After unlocking you have standard behavior about using
104                        * of empty resources. If resource is unloaded, so empty resource will be used.
105                        *
106                        * @return true if unlocking was successfull otherwise false
107                        * @note In complement of the locking, you are always able to unlock.
108                        *               If the lock state stack is empty and you are unlocking the resource, so this
109                        *               do not affect anything.
110                        **/
111                        void unlockPure();
112                       
113                        /**
114                        * Reset the stored resource to a new value
115                        **/
116                        void resetRes(IResource* res);
117               
118                        /**
119                        * Returns true if this holder has a pointer to a empty resource
120                        **/
121                        NR_FORCEINLINE bool hasEmpty() const{
122                                return mEmptyResource == NULL;
123                        }
124               
125                        /**
126                        * Return the number of access to this resource
127                        **/
128                        NR_FORCEINLINE uint32 getAccessCount() const{
129                                return countAccess;
130                        }
131                       
132                        /**
133                        * Each access to the resource will should call this function. Here
134                        * we do work that has to be done if a resource was used.
135                        **/
136                        NR_FORCEINLINE void touchResource(){
137                                // count up the access count variable
138                                countAccess ++;
139                        }
140                       
141                        /**
142                        * Check whenever the resource is currently locked
143                        **/
144                        NR_FORCEINLINE bool isLocked(){
145                                if (mLockStackTop > 0) 
146                                        return mLockStack[mLockStackTop - 1];
147                                else
148                                        return false;
149                        }
150                       
151                        /**
152                        * This will bind this holder to specific empty resource.
153                        * After loading of a resource from a file the manager will
154                        * create/load the empty resource according to the type of the resource.
155                        * Then it will generate a name for it and will bind the holder to that
156                        * empty resource. So if you will next load a resource of the same type,
157                        * so holder's empty resource pointer will still point to the same one.
158                        **/
159                        void setEmptyResource(IResource* res);
160                        //void setEmptyResource(SharedPtr<IResource> res);
161               
162                        /**
163                        * Returns the empty resource of the resource type holded by this holder.
164                        **/
165                        IResource* getEmpty();
166               
167                       
168                        /**
169                        * Get access to the stored resource.
170                        * We declare this function as private, so we cannot access to the resource
171                        * from outside either as from manager or a smart pointer to resources.
172                        * We need to do it in such a way, to prevent you from deleting the resources
173                        * from outside as from the resource management system.
174                        *
175                        * If the resource is temporary unloaded or if it is not exists, the holder will
176                        * give you the empty resource back, which still can be NULL or not
177                        *
178                        * Each call of getResource() method will count up the access number.
179                        **/
180                        IResource* getResource();
181                               
182        };
183
184        /// @endcond
185};
186#endif
Note: See TracBrowser for help on using the repository browser.