openscenegraph
Node
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
15#ifndef OSG_NODE
16#define OSG_NODE 1
17
18#include <osg/Object>
19#include <osg/StateSet>
20#include <osg/BoundingSphere>
21#include <osg/BoundingBox>
22#include <osg/Callback>
23
24#include <string>
25#include <vector>
26
27
28// forward declare osgTerrrain::Terrain to enable declaration of asTerrain() method.
29namespace osgTerrain {
30class Terrain;
31}
32
33namespace osg {
34
35// forcing declare classes to enable declaration of as*() methods.
36class NodeVisitor;
37class Drawable;
38class Geometry;
39class Group;
40class Transform;
41class Node;
42class Switch;
43class Geode;
44class Camera;
45
46/** A vector of Nodes pointers which is used to describe the path from a root node to a descendant.*/
47typedef std::vector< Node* > NodePath;
48
49/** A vector of NodePath, typically used to describe all the paths from a node to the potential root nodes it has.*/
50typedef std::vector< NodePath > NodePathList;
51
52/** A vector of NodePath, typically used to describe all the paths from a node to the potential root nodes it has.*/
53typedef std::vector< Matrix > MatrixList;
54
55
56/** META_Node macro define the standard clone, isSameKindAs, className
57 * and accept methods. Use when subclassing from Node to make it
58 * more convenient to define the required pure virtual methods.*/
59#define META_Node(library,name) \
60 virtual osg::Object* cloneType() const { return new name (); } \
61 virtual osg::Object* clone(const osg::CopyOp& copyop) const { return new name (*this,copyop); } \
62 virtual bool isSameKindAs(const osg::Object* obj) const { return dynamic_cast<const name *>(obj)!=NULL; } \
63 virtual const char* className() const { return #name; } \
64 virtual const char* libraryName() const { return #library; } \
65 virtual void accept(osg::NodeVisitor& nv) { if (nv.validNodeMask(*this)) { nv.pushOntoNodePath(this); nv.apply(*this); nv.popFromNodePath(); } } \
66
67
68/** Base class for all internal nodes in the scene graph.
69 Provides interface for most common node operations (Composite Pattern).
70*/
71class OSG_EXPORT Node : public Object
72{
73 public:
74
75 /** Construct a node.
76 Initialize the parent list to empty, node name to "" and
77 bounding sphere dirty flag to true.*/
78 Node();
79
80 /** Copy constructor using CopyOp to manage deep vs shallow copy.*/
81 Node(const Node&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
82
83 /** clone an object of the same type as the node.*/
84 virtual Object* cloneType() const { return new Node(); }
85
86 /** return a clone of a node, with Object* return type.*/
87 virtual Object* clone(const CopyOp& copyop) const { return new Node(*this,copyop); }
88
89 /** return true if this and obj are of the same kind of object.*/
90 virtual bool isSameKindAs(const Object* obj) const { return dynamic_cast<const Node*>(obj)!=NULL; }
91
92 /** return the name of the node's library.*/
93 virtual const char* libraryName() const { return "osg"; }
94
95 /** return the name of the node's class type.*/
96 virtual const char* className() const { return "Node"; }
97
98 /** Convert 'this' into a Node pointer if Object is a Node, otherwise return 0.
99 * Equivalent to dynamic_cast<Node*>(this).*/
100 virtual Node* asNode() { return this; }
101
102 /** convert 'const this' into a const Node pointer if Object is a Node, otherwise return 0.
103 * Equivalent to dynamic_cast<const Node*>(this).*/
104 virtual const Node* asNode() const { return this; }
105
106 /** convert 'this' into a Drawable pointer if Node is a Drawable, otherwise return 0.
107 * Equivalent to dynamic_cast<Group*>(this).*/
108 virtual Drawable* asDrawable() { return 0; }
109 /** convert 'const this' into a const Drawable pointer if Node is a Drawable, otherwise return 0.
110 * Equivalent to dynamic_cast<const Group*>(this).*/
111 virtual const Drawable* asDrawable() const { return 0; }
112
113 /** convert 'this' into a Geometry pointer if Node is a Geometry, otherwise return 0.
114 * Equivalent to dynamic_cast<Group*>(this).*/
115 virtual Geometry* asGeometry() { return 0; }
116 /** convert 'const this' into a const Geometry pointer if Node is a Geometry, otherwise return 0.
117 * Equivalent to dynamic_cast<const Group*>(this).*/
118 virtual const Geometry* asGeometry() const { return 0; }
119
120 /** convert 'this' into a Group pointer if Node is a Group, otherwise return 0.
121 * Equivalent to dynamic_cast<Group*>(this).*/
122 virtual Group* asGroup() { return 0; }
123 /** convert 'const this' into a const Group pointer if Node is a Group, otherwise return 0.
124 * Equivalent to dynamic_cast<const Group*>(this).*/
125 virtual const Group* asGroup() const { return 0; }
126
127 /** Convert 'this' into a Transform pointer if Node is a Transform, otherwise return 0.
128 * Equivalent to dynamic_cast<Transform*>(this).*/
129 virtual Transform* asTransform() { return 0; }
130
131 /** convert 'const this' into a const Transform pointer if Node is a Transform, otherwise return 0.
132 * Equivalent to dynamic_cast<const Transform*>(this).*/
133 virtual const Transform* asTransform() const { return 0; }
134
135
136
137 /** Convert 'this' into a Switch pointer if Node is a Switch, otherwise return 0.
138 * Equivalent to dynamic_cast<Switch*>(this).*/
139 virtual Switch* asSwitch() { return 0; }
140
141 /** convert 'const this' into a const Switch pointer if Node is a Switch, otherwise return 0.
142 * Equivalent to dynamic_cast<const Switch*>(this).*/
143 virtual const Switch* asSwitch() const { return 0; }
144
145 /** Convert 'this' into a Geode pointer if Node is a Geode, otherwise return 0.
146 * Equivalent to dynamic_cast<Geode*>(this).*/
147 virtual Geode* asGeode() { return 0; }
148
149 /** convert 'const this' into a const Geode pointer if Node is a Geode, otherwise return 0.
150 * Equivalent to dynamic_cast<const Geode*>(this).*/
151 virtual const Geode* asGeode() const { return 0; }
152
153 /** Convert 'this' into a Transform pointer if Node is a Terrain, otherwise return 0.
154 * Equivalent to dynamic_cast<Terrrain*>(this).*/
155 virtual osgTerrain::Terrain* asTerrain() { return 0; }
156
157 /** convert 'const this' into a const Terrain pointer if Node is a Terrain, otherwise return 0.
158 * Equivalent to dynamic_cast<const Terrain*>(this).*/
159 virtual const osgTerrain::Terrain* asTerrain() const { return 0; }
160
161
162 /** Visitor Pattern : calls the apply method of a NodeVisitor with this node's type.*/
163 virtual void accept(NodeVisitor& nv);
164 /** Traverse upwards : calls parents' accept method with NodeVisitor.*/
165 virtual void ascend(NodeVisitor& nv);
166 /** Traverse downwards : calls children's accept method with NodeVisitor.*/
167 virtual void traverse(NodeVisitor& /*nv*/) {}
168
169 /** A vector of osg::Group pointers which is used to store the parent(s) of node.*/
170 typedef std::vector<Group*> ParentList;
171
172 /** Get the parent list of node. */
173 inline const ParentList& getParents() const { return _parents; }
174
175 /** Get the a copy of parent list of node. A copy is returned to
176 * prevent modification of the parent list.*/
177 inline ParentList getParents() { return _parents; }
178
179 inline Group* getParent(unsigned int i) { return _parents[i]; }
180
181 /**
182 * Get a single const parent of node.
183 * @param i index of the parent to get.
184 * @return the parent i.
185 */
186 inline const Group* getParent(unsigned int i) const { return _parents[i]; }
187
188 /**
189 * Get the number of parents of node.
190 * @return the number of parents of this node.
191 */
192 inline unsigned int getNumParents() const { return static_cast<unsigned int>(_parents.size()); }
193
194
195
196 /** Get the list of node paths parent paths.
197 * The optional Node* haltTraversalAtNode allows the user to prevent traversal beyond a specified node. */
198 NodePathList getParentalNodePaths(osg::Node* haltTraversalAtNode=0) const;
199
200 /** Get the list of matrices that transform this node from local coordinates to world coordinates.
201 * The optional Node* haltTraversalAtNode allows the user to prevent traversal beyond a specified node. */
202 MatrixList getWorldMatrices(const osg::Node* haltTraversalAtNode=0) const;
203
204
205 /** Set update node callback, called during update traversal. */
206 void setUpdateCallback(Callback* nc);
207
208 template<class T> void setUpdateCallback(const ref_ptr<T>& nc) { setUpdateCallback(nc.get()); }
209
210 /** Get update node callback, called during update traversal. */
211 inline Callback* getUpdateCallback() { return _updateCallback.get(); }
212
213 /** Get const update node callback, called during update traversal. */
214 inline const Callback* getUpdateCallback() const { return _updateCallback.get(); }
215
216 /** Convenience method that sets the update callback of the node if it doesn't exist, or nest it into the existing one. */
217 inline void addUpdateCallback(Callback* nc) {
218 if (nc != NULL) {
219 if (_updateCallback.valid()) _updateCallback->addNestedCallback(nc);
220 else setUpdateCallback(nc);
221 }
222 }
223
224 template<class T> void addUpdateCallback(const ref_ptr<T>& nc) { addUpdateCallback(nc.get()); }
225
226 /** Convenience method that removes a given callback from a node, even if that callback is nested. There is no error return in case the given callback is not found. */
227 inline void removeUpdateCallback(Callback* nc) {
228 if (nc != NULL && _updateCallback.valid()) {
229 if (_updateCallback == nc)
230 {
231 ref_ptr<osg::Callback> new_nested_callback = nc->getNestedCallback();
232 nc->setNestedCallback(0);
233 setUpdateCallback(new_nested_callback.get());
234 }
235 else _updateCallback->removeNestedCallback(nc);
236 }
237 }
238
239 template<class T> void removeUpdateCallback(const ref_ptr<T>& nc) { removeUpdateCallback(nc.get()); }
240
241 /** Get the number of Children of this node which require Update traversal,
242 * since they have an Update Callback attached to them or their children.*/
243 inline unsigned int getNumChildrenRequiringUpdateTraversal() const { return _numChildrenRequiringUpdateTraversal; }
244
245
246 /** Set event node callback, called during event traversal. */
247 void setEventCallback(Callback* nc);
248
249 template<class T> void setEventCallback(const ref_ptr<T>& nc) { setEventCallback(nc.get()); }
250
251 /** Get event node callback, called during event traversal. */
252 inline Callback* getEventCallback() { return _eventCallback.get(); }
253
254 /** Get const event node callback, called during event traversal. */
255 inline const Callback* getEventCallback() const { return _eventCallback.get(); }
256
257 /** Convenience method that sets the event callback of the node if it doesn't exist, or nest it into the existing one. */
258 inline void addEventCallback(Callback* nc) {
259 if (nc != NULL) {
260 if (_eventCallback.valid()) _eventCallback->addNestedCallback(nc);
261 else setEventCallback(nc);
262 }
263 }
264
265 template<class T> void addEventCallback(const ref_ptr<T>& nc) { addEventCallback(nc.get()); }
266
267 /** Convenience method that removes a given callback from a node, even if that callback is nested. There is no error return in case the given callback is not found. */
268 inline void removeEventCallback(Callback* nc) {
269 if (nc != NULL && _eventCallback.valid()) {
270 if (_eventCallback == nc)
271 {
272 ref_ptr<osg::Callback> new_nested_callback = nc->getNestedCallback();
273 nc->setNestedCallback(0);
274 setEventCallback(new_nested_callback.get()); // replace the callback by the nested one
275 }
276 else _eventCallback->removeNestedCallback(nc);
277 }
278 }
279
280 template<class T> void removeEventCallback(const ref_ptr<T>& nc) { removeEventCallback(nc.get()); }
281
282 /** Get the number of Children of this node which require Event traversal,
283 * since they have an Event Callback attached to them or their children.*/
284 inline unsigned int getNumChildrenRequiringEventTraversal() const { return _numChildrenRequiringEventTraversal; }
285
286
287 /** Set cull node callback, called during cull traversal. */
288 void setCullCallback(Callback* nc) { _cullCallback = nc; }
289
290 template<class T> void setCullCallback(const ref_ptr<T>& nc) { setCullCallback(nc.get()); }
291
292 /** Get cull node callback, called during cull traversal. */
293 inline Callback* getCullCallback() { return _cullCallback.get(); }
294
295 /** Get const cull node callback, called during cull traversal. */
296 inline const Callback* getCullCallback() const { return _cullCallback.get(); }
297
298 /** Convenience method that sets the cull callback of the node if it doesn't exist, or nest it into the existing one. */
299 inline void addCullCallback(Callback* nc) {
300 if (nc != NULL) {
301 if (_cullCallback.valid()) _cullCallback->addNestedCallback(nc);
302 else setCullCallback(nc);
303 }
304 }
305
306 template<class T> void addCullCallback(const ref_ptr<T>& nc) { addCullCallback(nc.get()); }
307
308 /** Convenience method that removes a given callback from a node, even if that callback is nested. There is no error return in case the given callback is not found. */
309 inline void removeCullCallback(Callback* nc) {
310 if (nc != NULL && _cullCallback.valid()) {
311 if (_cullCallback == nc)
312 {
313 ref_ptr<osg::Callback> new_nested_callback = nc->getNestedCallback();
314 nc->setNestedCallback(0);
315 setCullCallback(new_nested_callback.get()); // replace the callback by the nested one
316 }
317 else _cullCallback->removeNestedCallback(nc);
318 }
319 }
320
321 template<class T> void removeCullCallback(const ref_ptr<T>& nc) { removeCullCallback(nc.get()); }
322
323 /** Set the view frustum/small feature culling of this node to be active or inactive.
324 * The default value is true for _cullingActive. Used as a guide
325 * to the cull traversal.*/
326 void setCullingActive(bool active);
327
328 /** Get the view frustum/small feature _cullingActive flag for this node. Used as a guide
329 * to the cull traversal.*/
330 inline bool getCullingActive() const { return _cullingActive; }
331
332 /** Get the number of Children of this node which have culling disabled.*/
333 inline unsigned int getNumChildrenWithCullingDisabled() const { return _numChildrenWithCullingDisabled; }
334
335 /** Return true if this node can be culled by view frustum, occlusion or small feature culling during the cull traversal.
336 * Note, returns true only if no children have culling disabled, and the local _cullingActive flag is true.*/
337 inline bool isCullingActive() const { return _numChildrenWithCullingDisabled==0 && _cullingActive && getBound().valid(); }
338
339 /** Get the number of Children of this node which are or have OccluderNode's.*/
340 inline unsigned int getNumChildrenWithOccluderNodes() const { return _numChildrenWithOccluderNodes; }
341
342
343 /** return true if this node is an OccluderNode or the subgraph below this node are OccluderNodes.*/
344 bool containsOccluderNodes() const;
345
346
347 /**
348 * This is a set of bits (flags) that represent the Node.
349 * The default value is 0xffffffff (all bits set).
350 *
351 * The most common use of these is during traversal of the scene graph.
352 * For instance, when traversing the scene graph the osg::NodeVisitor does a bitwise
353 * AND of its TraversalMask with the Node's NodeMask to
354 * determine if the Node should be processed/traversed.
355 *
356 * For example, if a Node has a NodeMask value of 0x02 (only 2nd bit set)
357 * and the osg::Camera has a CullMask of 0x4 (2nd bit not set) then during cull traversal,
358 * which takes it's TraversalMask from the Camera's CullMask, the node and any children
359 * would be ignored and thereby treated as "culled" and thus not rendered.
360 * Conversely, if the osg::Camera CullMask were 0x3 (2nd bit set) then the node
361 * would be processed and child Nodes would be examined.
362 */
363 typedef unsigned int NodeMask;
364 /** Set the node mask.*/
365 inline void setNodeMask(NodeMask nm) { _nodeMask = nm; }
366 /** Get the node Mask.*/
367 inline NodeMask getNodeMask() const { return _nodeMask; }
368
369
370
371 /** Set the node's StateSet.*/
372 void setStateSet(osg::StateSet* stateset);
373
374 template<class T> void setStateSet(const osg::ref_ptr<T>& stateset) { setStateSet(stateset.get()); }
375
376 /** return the node's StateSet, if one does not already exist create it
377 * set the node and return the newly created StateSet. This ensures
378 * that a valid StateSet is always returned and can be used directly.*/
379 osg::StateSet* getOrCreateStateSet();
380
381 /** Return the node's StateSet. returns NULL if a stateset is not attached.*/
382 inline osg::StateSet* getStateSet() { return _stateset.get(); }
383
384 /** Return the node's const StateSet. Returns NULL if a stateset is not attached.*/
385 inline const osg::StateSet* getStateSet() const { return _stateset.get(); }
386
387
388 /** A vector of std::string's which are used to describe the object.*/
389 typedef std::vector<std::string> DescriptionList;
390
391 /** Set the list of string descriptions.*/
392 void setDescriptions(const DescriptionList& descriptions);
393
394 /** Get the description list of the node.*/
395 DescriptionList& getDescriptions();
396
397 /** Get the const description list of the const node.*/
398 const DescriptionList& getDescriptions() const;
399
400
401 /** Get a single const description of the const node.*/
402 const std::string& getDescription(unsigned int i) const;
403
404 /** Get a single description of the node.*/
405 std::string& getDescription(unsigned int i);
406
407 /** Get the number of descriptions of the node.*/
408 unsigned int getNumDescriptions() const;
409
410 /** Add a description string to the node.*/
411 void addDescription(const std::string& desc);
412
413
414 /** Set the initial bounding volume to use when computing the overall bounding volume.*/
415 void setInitialBound(const osg::BoundingSphere& bsphere) { _initialBound = bsphere; dirtyBound(); }
416
417 /** Set the initial bounding volume to use when computing the overall bounding volume.*/
418 const BoundingSphere& getInitialBound() const { return _initialBound; }
419
420 /** Mark this node's bounding sphere dirty.
421 Forcing it to be computed on the next call to getBound().*/
422 void dirtyBound();
423
424
425 inline const BoundingSphere& getBound() const
426 {
427 if(!_boundingSphereComputed)
428 {
429 _boundingSphere = _initialBound;
430 if (_computeBoundCallback.valid())
431 _boundingSphere.expandBy(_computeBoundCallback->computeBound(*this));
432 else
433 _boundingSphere.expandBy(computeBound());
434
435 _boundingSphereComputed = true;
436 }
437 return _boundingSphere;
438 }
439
440 /** Compute the bounding sphere around Node's geometry or children.
441 This method is automatically called by getBound() when the bounding
442 sphere has been marked dirty via dirtyBound().*/
443 virtual BoundingSphere computeBound() const;
444
445 /** Callback to allow users to override the default computation of bounding volume.*/
446 struct ComputeBoundingSphereCallback : public osg::Object
447 {
448 ComputeBoundingSphereCallback() {}
449
450 ComputeBoundingSphereCallback(const ComputeBoundingSphereCallback& org,const CopyOp& copyop):
451 Object(org, copyop) {}
452
453 META_Object(osg,ComputeBoundingSphereCallback);
454
455 virtual BoundingSphere computeBound(const osg::Node&) const { return BoundingSphere(); }
456 };
457
458 /** Set the compute bound callback to override the default computeBound.*/
459 void setComputeBoundingSphereCallback(ComputeBoundingSphereCallback* callback) { _computeBoundCallback = callback; }
460
461 template<class T> void setComputeBoundingSphereCallback(const ref_ptr<T>& callback) { setComputeBoundingSphereCallback(callback.get()); }
462
463 /** Get the compute bound callback.*/
464 ComputeBoundingSphereCallback* getComputeBoundingSphereCallback() { return _computeBoundCallback.get(); }
465
466 /** Get the const compute bound callback.*/
467 const ComputeBoundingSphereCallback* getComputeBoundingSphereCallback() const { return _computeBoundCallback.get(); }
468
469 /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
470 virtual void setThreadSafeRefUnref(bool threadSafe);
471
472 /** Resize any per context GLObject buffers to specified size. */
473 virtual void resizeGLObjectBuffers(unsigned int /*maxSize*/);
474
475 /** If State is non-zero, this function releases any associated OpenGL objects for
476 * the specified graphics context. Otherwise, releases OpenGL objects
477 * for all graphics contexts. */
478 virtual void releaseGLObjects(osg::State* = 0) const;
479
480
481 protected:
482
483 /** Node destructor. Note, is protected so that Nodes cannot
484 be deleted other than by being dereferenced and the reference
485 count being zero (see osg::Referenced), preventing the deletion
486 of nodes which are still in use. This also means that
487 Nodes cannot be created on stack i.e Node node will not compile,
488 forcing all nodes to be created on the heap i.e Node* node
489 = new Node().*/
490 virtual ~Node();
491
492
493
494 BoundingSphere _initialBound;
495 ref_ptr<ComputeBoundingSphereCallback> _computeBoundCallback;
496 mutable BoundingSphere _boundingSphere;
497 mutable bool _boundingSphereComputed;
498
499 void addParent(osg::Group* parent);
500 void removeParent(osg::Group* parent);
501
502 ParentList _parents;
503 friend class osg::Group;
504 friend class osg::Drawable;
505 friend class osg::StateSet;
506
507 ref_ptr<Callback> _updateCallback;
508 unsigned int _numChildrenRequiringUpdateTraversal;
509 void setNumChildrenRequiringUpdateTraversal(unsigned int num);
510
511 ref_ptr<Callback> _eventCallback;
512 unsigned int _numChildrenRequiringEventTraversal;
513 void setNumChildrenRequiringEventTraversal(unsigned int num);
514
515 ref_ptr<Callback> _cullCallback;
516
517 bool _cullingActive;
518 unsigned int _numChildrenWithCullingDisabled;
519 void setNumChildrenWithCullingDisabled(unsigned int num);
520
521 unsigned int _numChildrenWithOccluderNodes;
522 void setNumChildrenWithOccluderNodes(unsigned int num);
523
524 NodeMask _nodeMask;
525
526 ref_ptr<StateSet> _stateset;
527
528};
529
530}
531
532#endif