diff options
Diffstat (limited to 'libraries/irrlicht-1.8/include/IReferenceCounted.h')
-rw-r--r-- | libraries/irrlicht-1.8/include/IReferenceCounted.h | 340 |
1 files changed, 170 insertions, 170 deletions
diff --git a/libraries/irrlicht-1.8/include/IReferenceCounted.h b/libraries/irrlicht-1.8/include/IReferenceCounted.h index 8a551e8..0eb23a5 100644 --- a/libraries/irrlicht-1.8/include/IReferenceCounted.h +++ b/libraries/irrlicht-1.8/include/IReferenceCounted.h | |||
@@ -1,170 +1,170 @@ | |||
1 | // Copyright (C) 2002-2012 Nikolaus Gebhardt | 1 | // Copyright (C) 2002-2012 Nikolaus Gebhardt |
2 | // This file is part of the "Irrlicht Engine". | 2 | // This file is part of the "Irrlicht Engine". |
3 | // For conditions of distribution and use, see copyright notice in irrlicht.h | 3 | // For conditions of distribution and use, see copyright notice in irrlicht.h |
4 | 4 | ||
5 | #ifndef __I_IREFERENCE_COUNTED_H_INCLUDED__ | 5 | #ifndef __I_IREFERENCE_COUNTED_H_INCLUDED__ |
6 | #define __I_IREFERENCE_COUNTED_H_INCLUDED__ | 6 | #define __I_IREFERENCE_COUNTED_H_INCLUDED__ |
7 | 7 | ||
8 | #include "irrTypes.h" | 8 | #include "irrTypes.h" |
9 | 9 | ||
10 | namespace irr | 10 | namespace irr |
11 | { | 11 | { |
12 | 12 | ||
13 | //! Base class of most objects of the Irrlicht Engine. | 13 | //! Base class of most objects of the Irrlicht Engine. |
14 | /** This class provides reference counting through the methods grab() and drop(). | 14 | /** This class provides reference counting through the methods grab() and drop(). |
15 | It also is able to store a debug string for every instance of an object. | 15 | It also is able to store a debug string for every instance of an object. |
16 | Most objects of the Irrlicht | 16 | Most objects of the Irrlicht |
17 | Engine are derived from IReferenceCounted, and so they are reference counted. | 17 | Engine are derived from IReferenceCounted, and so they are reference counted. |
18 | 18 | ||
19 | When you create an object in the Irrlicht engine, calling a method | 19 | When you create an object in the Irrlicht engine, calling a method |
20 | which starts with 'create', an object is created, and you get a pointer | 20 | which starts with 'create', an object is created, and you get a pointer |
21 | to the new object. If you no longer need the object, you have | 21 | to the new object. If you no longer need the object, you have |
22 | to call drop(). This will destroy the object, if grab() was not called | 22 | to call drop(). This will destroy the object, if grab() was not called |
23 | in another part of you program, because this part still needs the object. | 23 | in another part of you program, because this part still needs the object. |
24 | Note, that you only need to call drop() to the object, if you created it, | 24 | Note, that you only need to call drop() to the object, if you created it, |
25 | and the method had a 'create' in it. | 25 | and the method had a 'create' in it. |
26 | 26 | ||
27 | A simple example: | 27 | A simple example: |
28 | 28 | ||
29 | If you want to create a texture, you may want to call an imaginable method | 29 | If you want to create a texture, you may want to call an imaginable method |
30 | IDriver::createTexture. You call | 30 | IDriver::createTexture. You call |
31 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); | 31 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); |
32 | If you no longer need the texture, call texture->drop(). | 32 | If you no longer need the texture, call texture->drop(). |
33 | 33 | ||
34 | If you want to load a texture, you may want to call imaginable method | 34 | If you want to load a texture, you may want to call imaginable method |
35 | IDriver::loadTexture. You do this like | 35 | IDriver::loadTexture. You do this like |
36 | ITexture* texture = driver->loadTexture("example.jpg"); | 36 | ITexture* texture = driver->loadTexture("example.jpg"); |
37 | You will not have to drop the pointer to the loaded texture, because | 37 | You will not have to drop the pointer to the loaded texture, because |
38 | the name of the method does not start with 'create'. The texture | 38 | the name of the method does not start with 'create'. The texture |
39 | is stored somewhere by the driver. | 39 | is stored somewhere by the driver. |
40 | */ | 40 | */ |
41 | class IReferenceCounted | 41 | class IReferenceCounted |
42 | { | 42 | { |
43 | public: | 43 | public: |
44 | 44 | ||
45 | //! Constructor. | 45 | //! Constructor. |
46 | IReferenceCounted() | 46 | IReferenceCounted() |
47 | : DebugName(0), ReferenceCounter(1) | 47 | : DebugName(0), ReferenceCounter(1) |
48 | { | 48 | { |
49 | } | 49 | } |
50 | 50 | ||
51 | //! Destructor. | 51 | //! Destructor. |
52 | virtual ~IReferenceCounted() | 52 | virtual ~IReferenceCounted() |
53 | { | 53 | { |
54 | } | 54 | } |
55 | 55 | ||
56 | //! Grabs the object. Increments the reference counter by one. | 56 | //! Grabs the object. Increments the reference counter by one. |
57 | /** Someone who calls grab() to an object, should later also | 57 | /** Someone who calls grab() to an object, should later also |
58 | call drop() to it. If an object never gets as much drop() as | 58 | call drop() to it. If an object never gets as much drop() as |
59 | grab() calls, it will never be destroyed. The | 59 | grab() calls, it will never be destroyed. The |
60 | IReferenceCounted class provides a basic reference counting | 60 | IReferenceCounted class provides a basic reference counting |
61 | mechanism with its methods grab() and drop(). Most objects of | 61 | mechanism with its methods grab() and drop(). Most objects of |
62 | the Irrlicht Engine are derived from IReferenceCounted, and so | 62 | the Irrlicht Engine are derived from IReferenceCounted, and so |
63 | they are reference counted. | 63 | they are reference counted. |
64 | 64 | ||
65 | When you create an object in the Irrlicht engine, calling a | 65 | When you create an object in the Irrlicht engine, calling a |
66 | method which starts with 'create', an object is created, and | 66 | method which starts with 'create', an object is created, and |
67 | you get a pointer to the new object. If you no longer need the | 67 | you get a pointer to the new object. If you no longer need the |
68 | object, you have to call drop(). This will destroy the object, | 68 | object, you have to call drop(). This will destroy the object, |
69 | if grab() was not called in another part of you program, | 69 | if grab() was not called in another part of you program, |
70 | because this part still needs the object. Note, that you only | 70 | because this part still needs the object. Note, that you only |
71 | need to call drop() to the object, if you created it, and the | 71 | need to call drop() to the object, if you created it, and the |
72 | method had a 'create' in it. | 72 | method had a 'create' in it. |
73 | 73 | ||
74 | A simple example: | 74 | A simple example: |
75 | 75 | ||
76 | If you want to create a texture, you may want to call an | 76 | If you want to create a texture, you may want to call an |
77 | imaginable method IDriver::createTexture. You call | 77 | imaginable method IDriver::createTexture. You call |
78 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); | 78 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); |
79 | If you no longer need the texture, call texture->drop(). | 79 | If you no longer need the texture, call texture->drop(). |
80 | If you want to load a texture, you may want to call imaginable | 80 | If you want to load a texture, you may want to call imaginable |
81 | method IDriver::loadTexture. You do this like | 81 | method IDriver::loadTexture. You do this like |
82 | ITexture* texture = driver->loadTexture("example.jpg"); | 82 | ITexture* texture = driver->loadTexture("example.jpg"); |
83 | You will not have to drop the pointer to the loaded texture, | 83 | You will not have to drop the pointer to the loaded texture, |
84 | because the name of the method does not start with 'create'. | 84 | because the name of the method does not start with 'create'. |
85 | The texture is stored somewhere by the driver. */ | 85 | The texture is stored somewhere by the driver. */ |
86 | void grab() const { ++ReferenceCounter; } | 86 | void grab() const { ++ReferenceCounter; } |
87 | 87 | ||
88 | //! Drops the object. Decrements the reference counter by one. | 88 | //! Drops the object. Decrements the reference counter by one. |
89 | /** The IReferenceCounted class provides a basic reference | 89 | /** The IReferenceCounted class provides a basic reference |
90 | counting mechanism with its methods grab() and drop(). Most | 90 | counting mechanism with its methods grab() and drop(). Most |
91 | objects of the Irrlicht Engine are derived from | 91 | objects of the Irrlicht Engine are derived from |
92 | IReferenceCounted, and so they are reference counted. | 92 | IReferenceCounted, and so they are reference counted. |
93 | 93 | ||
94 | When you create an object in the Irrlicht engine, calling a | 94 | When you create an object in the Irrlicht engine, calling a |
95 | method which starts with 'create', an object is created, and | 95 | method which starts with 'create', an object is created, and |
96 | you get a pointer to the new object. If you no longer need the | 96 | you get a pointer to the new object. If you no longer need the |
97 | object, you have to call drop(). This will destroy the object, | 97 | object, you have to call drop(). This will destroy the object, |
98 | if grab() was not called in another part of you program, | 98 | if grab() was not called in another part of you program, |
99 | because this part still needs the object. Note, that you only | 99 | because this part still needs the object. Note, that you only |
100 | need to call drop() to the object, if you created it, and the | 100 | need to call drop() to the object, if you created it, and the |
101 | method had a 'create' in it. | 101 | method had a 'create' in it. |
102 | 102 | ||
103 | A simple example: | 103 | A simple example: |
104 | 104 | ||
105 | If you want to create a texture, you may want to call an | 105 | If you want to create a texture, you may want to call an |
106 | imaginable method IDriver::createTexture. You call | 106 | imaginable method IDriver::createTexture. You call |
107 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); | 107 | ITexture* texture = driver->createTexture(dimension2d<u32>(128, 128)); |
108 | If you no longer need the texture, call texture->drop(). | 108 | If you no longer need the texture, call texture->drop(). |
109 | If you want to load a texture, you may want to call imaginable | 109 | If you want to load a texture, you may want to call imaginable |
110 | method IDriver::loadTexture. You do this like | 110 | method IDriver::loadTexture. You do this like |
111 | ITexture* texture = driver->loadTexture("example.jpg"); | 111 | ITexture* texture = driver->loadTexture("example.jpg"); |
112 | You will not have to drop the pointer to the loaded texture, | 112 | You will not have to drop the pointer to the loaded texture, |
113 | because the name of the method does not start with 'create'. | 113 | because the name of the method does not start with 'create'. |
114 | The texture is stored somewhere by the driver. | 114 | The texture is stored somewhere by the driver. |
115 | \return True, if the object was deleted. */ | 115 | \return True, if the object was deleted. */ |
116 | bool drop() const | 116 | bool drop() const |
117 | { | 117 | { |
118 | // someone is doing bad reference counting. | 118 | // someone is doing bad reference counting. |
119 | _IRR_DEBUG_BREAK_IF(ReferenceCounter <= 0) | 119 | _IRR_DEBUG_BREAK_IF(ReferenceCounter <= 0) |
120 | 120 | ||
121 | --ReferenceCounter; | 121 | --ReferenceCounter; |
122 | if (!ReferenceCounter) | 122 | if (!ReferenceCounter) |
123 | { | 123 | { |
124 | delete this; | 124 | delete this; |
125 | return true; | 125 | return true; |
126 | } | 126 | } |
127 | 127 | ||
128 | return false; | 128 | return false; |
129 | } | 129 | } |
130 | 130 | ||
131 | //! Get the reference count. | 131 | //! Get the reference count. |
132 | /** \return Current value of the reference counter. */ | 132 | /** \return Current value of the reference counter. */ |
133 | s32 getReferenceCount() const | 133 | s32 getReferenceCount() const |
134 | { | 134 | { |
135 | return ReferenceCounter; | 135 | return ReferenceCounter; |
136 | } | 136 | } |
137 | 137 | ||
138 | //! Returns the debug name of the object. | 138 | //! Returns the debug name of the object. |
139 | /** The Debugname may only be set and changed by the object | 139 | /** The Debugname may only be set and changed by the object |
140 | itself. This method should only be used in Debug mode. | 140 | itself. This method should only be used in Debug mode. |
141 | \return Returns a string, previously set by setDebugName(); */ | 141 | \return Returns a string, previously set by setDebugName(); */ |
142 | const c8* getDebugName() const | 142 | const c8* getDebugName() const |
143 | { | 143 | { |
144 | return DebugName; | 144 | return DebugName; |
145 | } | 145 | } |
146 | 146 | ||
147 | protected: | 147 | protected: |
148 | 148 | ||
149 | //! Sets the debug name of the object. | 149 | //! Sets the debug name of the object. |
150 | /** The Debugname may only be set and changed by the object | 150 | /** The Debugname may only be set and changed by the object |
151 | itself. This method should only be used in Debug mode. | 151 | itself. This method should only be used in Debug mode. |
152 | \param newName: New debug name to set. */ | 152 | \param newName: New debug name to set. */ |
153 | void setDebugName(const c8* newName) | 153 | void setDebugName(const c8* newName) |
154 | { | 154 | { |
155 | DebugName = newName; | 155 | DebugName = newName; |
156 | } | 156 | } |
157 | 157 | ||
158 | private: | 158 | private: |
159 | 159 | ||
160 | //! The debug name. | 160 | //! The debug name. |
161 | const c8* DebugName; | 161 | const c8* DebugName; |
162 | 162 | ||
163 | //! The reference counter. Mutable to do reference counting on const objects. | 163 | //! The reference counter. Mutable to do reference counting on const objects. |
164 | mutable s32 ReferenceCounter; | 164 | mutable s32 ReferenceCounter; |
165 | }; | 165 | }; |
166 | 166 | ||
167 | } // end namespace irr | 167 | } // end namespace irr |
168 | 168 | ||
169 | #endif | 169 | #endif |
170 | 170 | ||