1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield
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.
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.
19#include <osg/StateSet>
20#include <osg/BoundingSphere>
21#include <osg/BoundingBox>
22#include <osg/Callback>
28// forward declare osgTerrrain::Terrain to enable declaration of asTerrain() method.
35// forcing declare classes to enable declaration of as*() methods.
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;
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;
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;
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(); } } \
68/** Base class for all internal nodes in the scene graph.
69 Provides interface for most common node operations (Composite Pattern).
71class OSG_EXPORT Node : public Object
76 Initialize the parent list to empty, node name to "" and
77 bounding sphere dirty flag to true.*/
80 /** Copy constructor using CopyOp to manage deep vs shallow copy.*/
81 Node(const Node&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
83 /** clone an object of the same type as the node.*/
84 virtual Object* cloneType() const { return new Node(); }
86 /** return a clone of a node, with Object* return type.*/
87 virtual Object* clone(const CopyOp& copyop) const { return new Node(*this,copyop); }
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; }
92 /** return the name of the node's library.*/
93 virtual const char* libraryName() const { return "osg"; }
95 /** return the name of the node's class type.*/
96 virtual const char* className() const { return "Node"; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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; }
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*/) {}
169 /** A vector of osg::Group pointers which is used to store the parent(s) of node.*/
170 typedef std::vector<Group*> ParentList;
172 /** Get the parent list of node. */
173 inline const ParentList& getParents() const { return _parents; }
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; }
179 inline Group* getParent(unsigned int i) { return _parents[i]; }
182 * Get a single const parent of node.
183 * @param i index of the parent to get.
184 * @return the parent i.
186 inline const Group* getParent(unsigned int i) const { return _parents[i]; }
189 * Get the number of parents of node.
190 * @return the number of parents of this node.
192 inline unsigned int getNumParents() const { return static_cast<unsigned int>(_parents.size()); }
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;
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;
205 /** Set update node callback, called during update traversal. */
206 void setUpdateCallback(Callback* nc);
208 template<class T> void setUpdateCallback(const ref_ptr<T>& nc) { setUpdateCallback(nc.get()); }
210 /** Get update node callback, called during update traversal. */
211 inline Callback* getUpdateCallback() { return _updateCallback.get(); }
213 /** Get const update node callback, called during update traversal. */
214 inline const Callback* getUpdateCallback() const { return _updateCallback.get(); }
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) {
219 if (_updateCallback.valid()) _updateCallback->addNestedCallback(nc);
220 else setUpdateCallback(nc);
224 template<class T> void addUpdateCallback(const ref_ptr<T>& nc) { addUpdateCallback(nc.get()); }
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)
231 ref_ptr<osg::Callback> new_nested_callback = nc->getNestedCallback();
232 nc->setNestedCallback(0);
233 setUpdateCallback(new_nested_callback.get());
235 else _updateCallback->removeNestedCallback(nc);
239 template<class T> void removeUpdateCallback(const ref_ptr<T>& nc) { removeUpdateCallback(nc.get()); }
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; }
246 /** Set event node callback, called during event traversal. */
247 void setEventCallback(Callback* nc);
249 template<class T> void setEventCallback(const ref_ptr<T>& nc) { setEventCallback(nc.get()); }
251 /** Get event node callback, called during event traversal. */
252 inline Callback* getEventCallback() { return _eventCallback.get(); }
254 /** Get const event node callback, called during event traversal. */
255 inline const Callback* getEventCallback() const { return _eventCallback.get(); }
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) {
260 if (_eventCallback.valid()) _eventCallback->addNestedCallback(nc);
261 else setEventCallback(nc);
265 template<class T> void addEventCallback(const ref_ptr<T>& nc) { addEventCallback(nc.get()); }
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)
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
276 else _eventCallback->removeNestedCallback(nc);
280 template<class T> void removeEventCallback(const ref_ptr<T>& nc) { removeEventCallback(nc.get()); }
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; }
287 /** Set cull node callback, called during cull traversal. */
288 void setCullCallback(Callback* nc) { _cullCallback = nc; }
290 template<class T> void setCullCallback(const ref_ptr<T>& nc) { setCullCallback(nc.get()); }
292 /** Get cull node callback, called during cull traversal. */
293 inline Callback* getCullCallback() { return _cullCallback.get(); }
295 /** Get const cull node callback, called during cull traversal. */
296 inline const Callback* getCullCallback() const { return _cullCallback.get(); }
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) {
301 if (_cullCallback.valid()) _cullCallback->addNestedCallback(nc);
302 else setCullCallback(nc);
306 template<class T> void addCullCallback(const ref_ptr<T>& nc) { addCullCallback(nc.get()); }
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)
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
317 else _cullCallback->removeNestedCallback(nc);
321 template<class T> void removeCullCallback(const ref_ptr<T>& nc) { removeCullCallback(nc.get()); }
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);
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; }
332 /** Get the number of Children of this node which have culling disabled.*/
333 inline unsigned int getNumChildrenWithCullingDisabled() const { return _numChildrenWithCullingDisabled; }
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(); }
339 /** Get the number of Children of this node which are or have OccluderNode's.*/
340 inline unsigned int getNumChildrenWithOccluderNodes() const { return _numChildrenWithOccluderNodes; }
343 /** return true if this node is an OccluderNode or the subgraph below this node are OccluderNodes.*/
344 bool containsOccluderNodes() const;
348 * This is a set of bits (flags) that represent the Node.
349 * The default value is 0xffffffff (all bits set).
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.
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.
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; }
371 /** Set the node's StateSet.*/
372 void setStateSet(osg::StateSet* stateset);
374 template<class T> void setStateSet(const osg::ref_ptr<T>& stateset) { setStateSet(stateset.get()); }
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();
381 /** Return the node's StateSet. returns NULL if a stateset is not attached.*/
382 inline osg::StateSet* getStateSet() { return _stateset.get(); }
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(); }
388 /** A vector of std::string's which are used to describe the object.*/
389 typedef std::vector<std::string> DescriptionList;
391 /** Set the list of string descriptions.*/
392 void setDescriptions(const DescriptionList& descriptions);
394 /** Get the description list of the node.*/
395 DescriptionList& getDescriptions();
397 /** Get the const description list of the const node.*/
398 const DescriptionList& getDescriptions() const;
401 /** Get a single const description of the const node.*/
402 const std::string& getDescription(unsigned int i) const;
404 /** Get a single description of the node.*/
405 std::string& getDescription(unsigned int i);
407 /** Get the number of descriptions of the node.*/
408 unsigned int getNumDescriptions() const;
410 /** Add a description string to the node.*/
411 void addDescription(const std::string& desc);
414 /** Set the initial bounding volume to use when computing the overall bounding volume.*/
415 void setInitialBound(const osg::BoundingSphere& bsphere) { _initialBound = bsphere; dirtyBound(); }
417 /** Set the initial bounding volume to use when computing the overall bounding volume.*/
418 const BoundingSphere& getInitialBound() const { return _initialBound; }
420 /** Mark this node's bounding sphere dirty.
421 Forcing it to be computed on the next call to getBound().*/
425 inline const BoundingSphere& getBound() const
427 if(!_boundingSphereComputed)
429 _boundingSphere = _initialBound;
430 if (_computeBoundCallback.valid())
431 _boundingSphere.expandBy(_computeBoundCallback->computeBound(*this));
433 _boundingSphere.expandBy(computeBound());
435 _boundingSphereComputed = true;
437 return _boundingSphere;
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;
445 /** Callback to allow users to override the default computation of bounding volume.*/
446 struct ComputeBoundingSphereCallback : public osg::Object
448 ComputeBoundingSphereCallback() {}
450 ComputeBoundingSphereCallback(const ComputeBoundingSphereCallback& org,const CopyOp& copyop):
451 Object(org, copyop) {}
453 META_Object(osg,ComputeBoundingSphereCallback);
455 virtual BoundingSphere computeBound(const osg::Node&) const { return BoundingSphere(); }
458 /** Set the compute bound callback to override the default computeBound.*/
459 void setComputeBoundingSphereCallback(ComputeBoundingSphereCallback* callback) { _computeBoundCallback = callback; }
461 template<class T> void setComputeBoundingSphereCallback(const ref_ptr<T>& callback) { setComputeBoundingSphereCallback(callback.get()); }
463 /** Get the compute bound callback.*/
464 ComputeBoundingSphereCallback* getComputeBoundingSphereCallback() { return _computeBoundCallback.get(); }
466 /** Get the const compute bound callback.*/
467 const ComputeBoundingSphereCallback* getComputeBoundingSphereCallback() const { return _computeBoundCallback.get(); }
469 /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
470 virtual void setThreadSafeRefUnref(bool threadSafe);
472 /** Resize any per context GLObject buffers to specified size. */
473 virtual void resizeGLObjectBuffers(unsigned int /*maxSize*/);
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;
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
494 BoundingSphere _initialBound;
495 ref_ptr<ComputeBoundingSphereCallback> _computeBoundCallback;
496 mutable BoundingSphere _boundingSphere;
497 mutable bool _boundingSphereComputed;
499 void addParent(osg::Group* parent);
500 void removeParent(osg::Group* parent);
503 friend class osg::Group;
504 friend class osg::Drawable;
505 friend class osg::StateSet;
507 ref_ptr<Callback> _updateCallback;
508 unsigned int _numChildrenRequiringUpdateTraversal;
509 void setNumChildrenRequiringUpdateTraversal(unsigned int num);
511 ref_ptr<Callback> _eventCallback;
512 unsigned int _numChildrenRequiringEventTraversal;
513 void setNumChildrenRequiringEventTraversal(unsigned int num);
515 ref_ptr<Callback> _cullCallback;
518 unsigned int _numChildrenWithCullingDisabled;
519 void setNumChildrenWithCullingDisabled(unsigned int num);
521 unsigned int _numChildrenWithOccluderNodes;
522 void setNumChildrenWithOccluderNodes(unsigned int num);
526 ref_ptr<StateSet> _stateset;