openscenegraph
Object
Go to the documentation of this file.
1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version. The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14#ifndef OSG_OBJECT
15#define OSG_OBJECT 1
16
17#include <osg/Referenced>
18#include <osg/CopyOp>
19#include <osg/ref_ptr>
20#include <osg/Notify>
21
22#include <string>
23#include <vector>
24
25namespace osg {
26
27// forward declare
28class UserDataContainer;
29class Node;
30class NodeVisitor;
31class StateAttribute;
32class Uniform;
33class Drawable;
34class Camera;
35class Callback;
36class CallbackObject;
37class ValueObject;
38
39#define _ADDQUOTES(def) #def
40#define ADDQUOTES(def) _ADDQUOTES(def)
41
42/** META_Object macro define the standard clone, isSameKindAs and className methods.
43 * Use when subclassing from Object to make it more convenient to define
44 * the standard pure virtual clone, isSameKindAs and className methods
45 * which are required for all Object subclasses.*/
46#define META_Object(library,name) \
47 virtual osg::Object* cloneType() const { return new name (); } \
48 virtual osg::Object* clone(const osg::CopyOp& copyop) const { return new name (*this,copyop); } \
49 virtual bool isSameKindAs(const osg::Object* obj) const { return dynamic_cast<const name *>(obj)!=NULL; } \
50 virtual const char* libraryName() const { return #library; }\
51 virtual const char* className() const { return #name; }
52
53/** Helper macro that creates a static proxy object to call singleton function on it's construction, ensuring that the singleton gets initialized at startup.*/
54#define OSG_INIT_SINGLETON_PROXY(ProxyName, Func) static struct ProxyName{ ProxyName() { Func; } } s_##ProxyName;
55
56/** Base class/standard interface for objects which require IO support,
57 cloning and reference counting.
58 Based on GOF Composite, Prototype and Template Method patterns.
59*/
60class OSG_EXPORT Object : public Referenced
61{
62 public:
63
64
65 /** Construct an object. Note Object is a pure virtual base class
66 and therefore cannot be constructed on its own, only derived
67 classes which override the clone and className methods are
68 concrete classes and can be constructed.*/
69 inline Object():Referenced(),_dataVariance(UNSPECIFIED), _userDataContainer(0) {}
70
71 inline explicit Object(bool threadSafeRefUnref):Referenced(threadSafeRefUnref),_dataVariance(UNSPECIFIED),_userDataContainer(0) {}
72
73 /** Copy constructor, optional CopyOp object can be used to control
74 * shallow vs deep copying of dynamic data.*/
75 Object(const Object&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
76
77 /** Clone the type of an object, with Object* return type.
78 Must be defined by derived classes.*/
79 virtual Object* cloneType() const = 0;
80
81 /** Clone an object, with Object* return type.
82 Must be defined by derived classes.*/
83 virtual Object* clone(const CopyOp&) const = 0;
84
85 virtual bool isSameKindAs(const Object*) const { return true; }
86
87
88 /** return the name of the object's library. Must be defined
89 by derived classes. The OpenSceneGraph convention is that the
90 namespace of a library is the same as the library name.*/
91 virtual const char* libraryName() const = 0;
92
93 /** return the name of the object's class type. Must be defined
94 by derived classes.*/
95 virtual const char* className() const = 0;
96
97 /** return the compound class name that combines the library name and class name.*/
98 std::string getCompoundClassName() const { return std::string(libraryName()) + std::string("::") + std::string(className()); }
99
100
101 /** Convert 'this' into a Node pointer if Object is a Node, otherwise return 0.
102 * Equivalent to dynamic_cast<Node*>(this).*/
103 virtual Node* asNode() { return 0; }
104
105 /** convert 'const this' into a const Node pointer if Object is a Node, otherwise return 0.
106 * Equivalent to dynamic_cast<const Node*>(this).*/
107 virtual const Node* asNode() const { return 0; }
108
109 /** Convert 'this' into a NodeVisitor pointer if Object is a NodeVisitor, otherwise return 0.
110 * Equivalent to dynamic_cast<NodeVisitor*>(this).*/
111 virtual NodeVisitor* asNodeVisitor() { return 0; }
112
113 /** convert 'const this' into a const NodeVisitor pointer if Object is a NodeVisitor, otherwise return 0.
114 * Equivalent to dynamic_cast<const NodeVisitor*>(this).*/
115 virtual const NodeVisitor* asNodeVisitor() const { return 0; }
116
117 /** Convert 'this' into a StateSet pointer if Object is a StateSet, otherwise return 0.
118 * Equivalent to dynamic_cast<StateSet*>(this).*/
119 virtual StateSet* asStateSet() { return 0; }
120
121 /** convert 'const this' into a const StateSet pointer if Object is a StateSet, otherwise return 0.
122 * Equivalent to dynamic_cast<const StateSet*>(this).*/
123 virtual const StateSet* asStateSet() const { return 0; }
124
125 /** Convert 'this' into a StateAttribute pointer if Object is a StateAttribute, otherwise return 0.
126 * Equivalent to dynamic_cast<StateAttribute*>(this).*/
127 virtual StateAttribute* asStateAttribute() { return 0; }
128
129 /** convert 'const this' into a const StateAttribute pointer if Object is a StateAttribute, otherwise return 0.
130 * Equivalent to dynamic_cast<const StateAttribute*>(this).*/
131 virtual const StateAttribute* asStateAttribute() const { return 0; }
132
133 /** Convert 'this' into a Uniform pointer if Object is a Uniform, otherwise return 0.
134 * Equivalent to dynamic_cast<Uniform*>(this).*/
135 virtual Uniform* asUniform() { return 0; }
136
137 /** convert 'const this' into a const Uniform pointer if Object is a Uniform, otherwise return 0.
138 * Equivalent to dynamic_cast<const Uniform*>(this).*/
139 virtual const Uniform* asUniform() const { return 0; }
140
141 /** Convert 'this' into a Camera pointer if Node is a Camera, otherwise return 0.
142 * Equivalent to dynamic_cast<Camera*>(this).*/
143 virtual Camera* asCamera() { return 0; }
144
145 /** convert 'const this' into a const Camera pointer if Node is a Camera, otherwise return 0.
146 * Equivalent to dynamic_cast<const Camera*>(this).*/
147 virtual const Camera* asCamera() const { return 0; }
148
149 /** Convert 'this' into a Drawable pointer if Object is a Drawable, otherwise return 0.
150 * Equivalent to dynamic_cast<Drawable*>(this).*/
151 virtual Drawable* asDrawable() { return 0; }
152
153 /** convert 'const this' into a const Drawable pointer if Object is a Drawable, otherwise return 0.
154 * Equivalent to dynamic_cast<const Drawable*>(this).*/
155 virtual const Drawable* asDrawable() const { return 0; }
156
157 /** Convert 'this' into a Callback pointer if Object is a Callback, otherwise return 0.
158 * Equivalent to dynamic_cast<Callback*>(this).*/
159 virtual Callback* asCallback() { return 0; }
160
161 /** convert 'const this' into a const Callback pointer if Object is a Callback, otherwise return 0.
162 * Equivalent to dynamic_cast<const Callback*>(this).*/
163 virtual const Callback* asCallback() const { return 0; }
164
165 /** Convert 'this' into a CallbackObject pointer if Object is a CallbackObject, otherwise return 0.
166 * Equivalent to dynamic_cast<CallbackObject*>(this).*/
167 virtual CallbackObject* asCallbackObject() { return 0; }
168
169 /** convert 'const this' into a const CallbackObject pointer if Object is a CallbackObject, otherwise return 0.
170 * Equivalent to dynamic_cast<const CallbackObject*>(this).*/
171 virtual const CallbackObject* asCallbackObject() const { return 0; }
172
173 /** Convert 'this' into a UserDataContainer pointer if Object is a UserDataContainer, otherwise return 0.
174 * Equivalent to dynamic_cast<UserDataContainer*>(this).*/
175 virtual UserDataContainer* asUserDataContainer() { return 0; }
176
177 /** convert 'const this' into a const UserDataContainer pointer if Object is a UserDataContainer, otherwise return 0.
178 * Equivalent to dynamic_cast<const UserDataContainer*>(this).*/
179 virtual const UserDataContainer* asUserDataContainer() const { return 0; }
180
181 /** Convert 'this' into a ValueObject pointer if Object is a ValueObject, otherwise return 0.
182 * Equivalent to dynamic_cast<ValueObject*>(this).*/
183 virtual ValueObject* asValueObject() { return 0; }
184
185 /** Convert 'this' into a ValueObject pointer if Object is a ValueObject, otherwise return 0.
186 * Equivalent to dynamic_cast<ValueObject*>(this).*/
187 virtual const ValueObject* asValueObject() const { return 0; }
188
189 /** Convert 'this' into a Image pointer if Object is a Image, otherwise return 0.
190 * Equivalent to dynamic_cast<Image*>(this).*/
191 virtual Image* asImage() { return 0; }
192
193 /** Convert 'this' into a Image pointer if Object is a Image, otherwise return 0.
194 * Equivalent to dynamic_cast<Image*>(this).*/
195 virtual const Image* asImage() const { return 0; }
196
197
198
199 /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
200 virtual void setThreadSafeRefUnref(bool threadSafe);
201
202 /** Set the name of object using C++ style string.*/
203 virtual void setName( const std::string& name ) { _name = name; }
204
205 /** Set the name of object using a C style string.*/
206 inline void setName( const char* name )
207 {
208 if (name) setName(std::string(name));
209 else setName(std::string());
210 }
211
212 /** Get the name of object.*/
213 inline const std::string& getName() const { return _name; }
214
215
216 enum DataVariance
217 {
218 DYNAMIC,
219 STATIC,
220 UNSPECIFIED
221 };
222
223 /** Set the data variance of this object.
224 * Can be set to either STATIC for values that do not change over the lifetime of the object,
225 * or DYNAMIC for values that vary over the lifetime of the object. The DataVariance value
226 * can be used by routines such as optimization codes that wish to share static data.
227 * UNSPECIFIED is used to specify that the DataVariance hasn't been set yet. */
228 inline void setDataVariance(DataVariance dv) { _dataVariance = dv; }
229
230 /** Get the data variance of this object.*/
231 inline DataVariance getDataVariance() const { return _dataVariance; }
232
233 /** Compute the DataVariance based on an assessment of callback etc.*/
234 virtual void computeDataVariance() {}
235
236
237 /** set the UserDataContainer object.*/
238 void setUserDataContainer(osg::UserDataContainer* udc);
239
240 template<class T> void setUserDataContainer(const ref_ptr<T>& udc) { setUserDataContainer(udc.get()); }
241
242 /** get the UserDataContainer attached to this object.*/
243 osg::UserDataContainer* getUserDataContainer() { return _userDataContainer; }
244
245 /** get the const UserDataContainer attached to this object.*/
246 const osg::UserDataContainer* getUserDataContainer() const { return _userDataContainer; }
247
248 /** Convenience method that returns the UserDataContainer, and if one doesn't already exist creates and assigns
249 * a DefaultUserDataContainer to the Object and then return this new UserDataContainer.*/
250 osg::UserDataContainer* getOrCreateUserDataContainer();
251
252
253 /**
254 * Set user data, data must be subclassed from Referenced to allow
255 * automatic memory handling. If your own data isn't directly
256 * subclassed from Referenced then create an adapter object
257 * which points to your own object and handles the memory addressing.
258 */
259 virtual void setUserData(Referenced* obj);
260
261 template<class T> void setUserData(const ref_ptr<T>& ud) { setUserData(ud.get()); }
262
263 /** Get user data.*/
264 virtual Referenced* getUserData();
265
266 /** Get const user data.*/
267 virtual const Referenced* getUserData() const;
268
269
270
271 /** Convenience method that casts the named UserObject to osg::TemplateValueObject<T> and gets the value.
272 * To use this template method you need to include the osg/ValueObject header.*/
273 template<typename T>
274 bool getUserValue(const std::string& name, T& value) const;
275
276 /** Convenience method that creates the osg::TemplateValueObject<T> to store the
277 * specified value and adds it as a named UserObject.
278 * To use this template method you need to include the osg/ValueObject header. */
279 template<typename T>
280 void setUserValue(const std::string& name, const T& value);
281
282
283 /** Resize any per context GLObject buffers to specified size. */
284 virtual void resizeGLObjectBuffers(unsigned int /*maxSize*/) {}
285
286 /** If State is non-zero, this function releases any associated OpenGL objects for
287 * the specified graphics context. Otherwise, releases OpenGL objects
288 * for all graphics contexts. */
289 virtual void releaseGLObjects(osg::State* = 0) const {}
290
291
292 protected:
293
294 /** Object destructor. Note, is protected so that Objects cannot
295 be deleted other than by being dereferenced and the reference
296 count being zero (see osg::Referenced), preventing the deletion
297 of nodes which are still in use. This also means that
298 Nodes cannot be created on stack i.e Node node will not compile,
299 forcing all nodes to be created on the heap i.e Node* node
300 = new Node().*/
301 virtual ~Object();
302
303 std::string _name;
304 DataVariance _dataVariance;
305
306 osg::UserDataContainer* _userDataContainer;
307
308 private:
309
310 /** disallow any copy operator.*/
311 Object& operator = (const Object&) { return *this; }
312};
313
314template<typename T>
315T* clone(const T* t, const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY)
316{
317 if (t)
318 {
319 osg::ref_ptr<osg::Object> obj = t->clone(copyop);
320
321 T* ptr = dynamic_cast<T*>(obj.get());
322 if (ptr)
323 {
324 obj.release();
325 return ptr;
326 }
327 else
328 {
329 OSG_WARN<<"Warning: osg::clone(const T*, osg::CopyOp&) cloned object not of type T, returning NULL."<<std::endl;
330 return 0;
331 }
332 }
333 else
334 {
335 OSG_WARN<<"Warning: osg::clone(const T*, osg::CopyOp&) passed null object to clone, returning NULL."<<std::endl;
336 return 0;
337 }
338}
339
340template<typename T>
341T* clone(const T* t, const std::string& name, const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY)
342{
343 T* newObject = osg::clone(t, copyop);
344 if (newObject)
345 {
346 newObject->setName(name);
347 return newObject;
348 }
349 else
350 {
351 OSG_WARN<<"Warning: osg::clone(const T*, const std::string&, const osg::CopyOp) passed null object to clone, returning NULL."<<std::endl;
352 return 0;
353 }
354}
355
356template<typename T>
357T* cloneType(const T* t)
358{
359 if (t)
360 {
361 osg::ref_ptr<osg::Object> obj = t->cloneType();
362
363 T* ptr = dynamic_cast<T*>(obj.get());
364 if (ptr)
365 {
366 obj.release();
367 return ptr;
368 }
369 else
370 {
371 OSG_WARN<<"Warning: osg::cloneType(const T*) cloned object not of type T, returning NULL."<<std::endl;
372 return 0;
373 }
374 }
375 else
376 {
377 OSG_WARN<<"Warning: osg::cloneType(const T*) passed null object to clone, returning NULL."<<std::endl;
378 return 0;
379 }
380}
381
382/** DummyObject that can be used as placeholder but otherwise has no other functionality.*/
383class DummyObject : public osg::Object
384{
385public:
386 DummyObject() {}
387 DummyObject(const DummyObject& org, const CopyOp& copyop) :
388 Object(org, copyop) {}
389
390 META_Object(osg, DummyObject)
391protected:
392 virtual ~DummyObject() {}
393};
394
395
396inline void resizeGLObjectBuffers(osg::Object* object, unsigned int maxSize) { if (object) object->resizeGLObjectBuffers(maxSize); }
397
398template<class T> void resizeGLObjectBuffers(const osg::ref_ptr<T>& object, unsigned int maxSize) { if (object.valid()) object->resizeGLObjectBuffers(maxSize); }
399
400inline void releaseGLObjects(osg::Object* object, osg::State* state = 0) { if (object) object->releaseGLObjects(state); }
401
402template<class T> void releaseGLObjects(const osg::ref_ptr<T>& object, osg::State* state = 0) { if (object.valid()) object->releaseGLObjects(state); }
403
404}
405
406#endif