diff --git a/include/osg/Drawable b/include/osg/Drawable index a26c072d4..1050a4e4b 100644 --- a/include/osg/Drawable +++ b/include/osg/Drawable @@ -1,13 +1,13 @@ -/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield +/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield * - * This library is open source and may be redistributed and/or modified under - * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or + * This library is open source and may be redistributed and/or modified under + * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or * (at your option) any later version. The full license is in LICENSE file * included with this distribution, and on the openscenegraph.org website. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * OpenSceneGraph Public License for more details. */ @@ -33,7 +33,7 @@ typedef int GLintptrARB; typedef int GLsizeiptrARB; #endif - + #define GL_ARRAY_BUFFER_ARB 0x8892 #define GL_ELEMENT_ARRAY_BUFFER_ARB 0x8893 #define GL_ARRAY_BUFFER_BINDING_ARB 0x8894 @@ -101,17 +101,28 @@ class Geometry; // this is defined to alter the way display lists are compiled inside the // the draw method, it has been found that the NVidia drivers fail completely -// to optimize COMPILE_AND_EXECUTE in fact make it go slower than for no display +// to optimize COMPILE_AND_EXECUTE in fact make it go slower than for no display // lists, but optimize a separate COMPILE very well?! Define it as default // the use of a separate COMPILE, then glCallList rather than use COMPILE_AND_EXECUTE. #define USE_SEPARATE_COMPILE_AND_EXECUTE -/** Pure virtual base class for drawable Geometry. Contains no drawing primitives - directly, these are provided by subclasses such as osg::Geometry. State attributes - for a Drawable are maintained in StateSet which the Drawable maintains - a referenced counted pointer to. Both Drawable's and StateSet's can - be shared for optimal memory usage and graphics performance. +/** Pure virtual base class for drawable geometry. In OSG, everything that can + * be rendered is implemented as a class derived from \c Drawable. The + * \c Drawable class contains no drawing primitives, since these are provided + * by subclasses such as \c osg::Geometry. + *

Notice that a \c Drawable is not a \c Node, and therefore it cannot be + * directly added to a scene graph. Instead, Drawables are attached to + * Geodes, which are scene graph nodes. + *

The OpenGL state that must be used when rendering a \c Drawable is + * represented by a \c StateSet. Since a \c Drawable has a reference + * (\c osg::ref_ptr) to a \c StateSet, StateSets can be shared between + * different Drawables. In fact, sharing StateSets is a good + * way to improve performance, since this allows OSG to reduce the number of + * expensive changes in the OpenGL state. + *

Finally, Drawables can also be shared between different + * Geodes, so that the same geometry (loaded to memory just once) can + * be used in different parts of the scene graph. */ class SG_EXPORT Drawable : public Object { @@ -130,10 +141,10 @@ class SG_EXPORT Drawable : public Object virtual const char* libraryName() const { return "osg"; } virtual const char* className() const { return "Drawable"; } - /** convert 'this' into a Geometry pointer if Drawable is a Geometry, otherwise return 0. + /** Convert 'this' into a Geometry pointer if Drawable is a Geometry, otherwise return 0. * Equivalent to dynamic_cast(this).*/ virtual Geometry* asGeometry() { return 0; } - /** convert 'const this' into a const Geometry pointer if Drawable is a Geometry, otherwise return 0. + /** Convert 'const this' into a const Geometry pointer if Drawable is a Geometry, otherwise return 0. * Equivalent to dynamic_cast(this).*/ virtual const Geometry* asGeometry() const { return 0; } @@ -144,7 +155,7 @@ class SG_EXPORT Drawable : public Object /** Get the parent list of drawable. */ inline const ParentList& getParents() const { return _parents; } - /** Get the a copy of parent list of node. A copy is returned to + /** Get the a copy of parent list of node. A copy is returned to * prevent modification of the parent list.*/ inline ParentList getParents() { return _parents; } @@ -168,28 +179,28 @@ class SG_EXPORT Drawable : public Object /** Set the StateSet attached to the Drawable. - Previously attached StateSet are automatically unreferenced on + Previously attached StateSet are automatically unreferenced on assignment of a new drawstate.*/ inline void setStateSet(StateSet *state) { _stateset = state; } - + /** Get the attached StateSet.*/ inline StateSet* getStateSet() { return _stateset.get();} /** Get the attached const StateSet.*/ inline const StateSet* getStateSet() const { return _stateset.get();} - /** Get the attached const StateSet, - * if one is not already attached create one, + /** Get the attached const StateSet, + * if one is not already attached create one, * attach it to the drawable and return a pointer to it.*/ StateSet* getOrCreateStateSet(); /** Dirty the bounding box, forcing a computeBound() on the next call * to getBound(). Should be called in the internal geometry of the Drawable - * is modified.*/ + * is modified.*/ void dirtyBound(); - /** get bounding box of geoset. + /** get bounding box of geoset. * Note, now made virtual to make it possible to implement user-drawn * objects albeit somewhat crudely, to be improved later. */ @@ -201,14 +212,16 @@ class SG_EXPORT Drawable : public Object } - /** Set the Shape of the drawable. The shape can be used to - * speed up collision detection or as a guide for procedural - * geometry generation - see osg::Shape.*/ + /** Set the Shape of the \c Drawable. The shape can be used to + * speed up collision detection or as a guide for procedural + * geometry generation. + * @see osg::Shape. + */ inline void setShape(Shape* shape) { _shape = shape; } /** Get the Shape of the Drawable.*/ inline Shape* getShape() { return _shape.get(); } - + /** Get the const Shape of the const Drawable.*/ inline const Shape* getShape() const { return _shape.get(); } @@ -222,8 +235,8 @@ class SG_EXPORT Drawable : public Object * on objects with dynamic internal data such as continuous Level of Detail * algorithms.*/ void setSupportsDisplayList(bool flag); - - /** Get whether display lists are supported for this drawable instance.*/ + + /** Get whether display lists are supported for this drawable instance.*/ inline bool getSupportsDisplayList() const { return _supportsDisplayList; } @@ -253,23 +266,27 @@ class SG_EXPORT Drawable : public Object - /** draw OpenGL primitives. - * If the drawable has _useDisplayList set to true then use an OpenGL display - * list, automatically compiling one if required. - * Otherwise call drawImplementation(). - * Note, draw method should *not* be overridden in subclasses as it - * manages the optional display list. + /** Draw OpenGL primitives. + * If the \c Drawable has \c _useDisplayList set to \c true, then use + * an OpenGL display list, automatically compiling one if required. + * Otherwise, call \c drawImplementation(). + * @note This method should \e not be overridden in subclasses, as it + * manages the optional display list (notice this is not even + * \c virtual). Subclasses should override + * \c drawImplementation() instead. */ inline void draw(State& state) const; - - /** Immediately compile this drawable into an OpenGL Display List. - Note I, operation is ignored if _useDisplayList to false. - Note II, compile is not intended to be overridden in subclasses.*/ + + /** Immediately compile this \c Drawable into an OpenGL Display List. + * @note Operation is ignored if \c _useDisplayList is \c false. + * @note This member function is not intended to be overridden in + * subclasses (notice that it is not even \c virtual). + */ virtual void compileGLObjects(State& state) const; - /** + /** if osg::State object is supplied: release any OpenGL display lists associated with graphics context specified - or + or if state pointer is NULL: release all display lists for all graphics contexts */ virtual void releaseGLObjects(State* state=0) const; @@ -284,16 +301,16 @@ class SG_EXPORT Drawable : public Object /** do customized update code.*/ virtual void update(osg::NodeVisitor*, osg::Drawable*) {} }; - + /** Set the UpdateCallback which allows users to attach customize the updating of an object during the update traversal.*/ virtual void setUpdateCallback(UpdateCallback* ac); - + /** Get the non const UpdateCallback.*/ UpdateCallback* getUpdateCallback() { return _updateCallback.get(); } /** Get the const UpdateCallback.*/ const UpdateCallback* getUpdateCallback() const { return _updateCallback.get(); } - + struct CullCallback : public virtual osg::Object { @@ -309,14 +326,14 @@ class SG_EXPORT Drawable : public Object /** Set the CullCallback which allows users to customize the culling of Drawable during the cull traversal.*/ virtual void setCullCallback(CullCallback* cc) { _cullCallback=cc; } - + /** Get the non const CullCallback.*/ CullCallback* getCullCallback() { return _cullCallback.get(); } - + /** Get the const CullCallback.*/ const CullCallback* getCullCallback() const { return _cullCallback.get(); } - - + + /** Callback attached to an Drawable which allows the users to customize the drawing of an exist Drawable object. @@ -338,18 +355,20 @@ class SG_EXPORT Drawable : public Object /** Set the DrawCallback which allows users to attach customize the drawing of existing Drawable object.*/ virtual void setDrawCallback(DrawCallback* dc) { _drawCallback=dc; dirtyDisplayList(); } - + /** Get the non const DrawCallback.*/ DrawCallback* getDrawCallback() { return _drawCallback.get(); } - + /** Get the const DrawCallback.*/ const DrawCallback* getDrawCallback() const { return _drawCallback.get(); } - /** draw directly ignoring an OpenGL display list which could be attached. - * This is the internal draw method which does the drawing itself, - * and is the method to override when deriving from Drawable. + /** Draw the \c Geometry "directly", that is, by issuing all the OpenGL + * calls needed to draw it. Contrast this with \c draw(), that can + * compile and use an OpenGL display list to do the rendering. + *

This is the internal draw method which does the drawing itself, + * and is the method to override when deriving from \c Drawable. */ virtual void drawImplementation(State& state) const = 0; @@ -363,32 +382,32 @@ class SG_EXPORT Drawable : public Object /** Get the minimum number of display lists to retain in the deleted display list cache. */ static unsigned int getMinimumNumberOfDisplayListsToRetainInCache(); - /** use deleteDisplayList instead of glDeleteList to allow + /** Use deleteDisplayList instead of glDeleteList to allow * OpenGL display list to be cached until they can be deleted * by the OpenGL context in which they were created, specified * by contextID.*/ static void deleteDisplayList(unsigned int contextID,GLuint globj, unsigned int sizeHint = 0); - - /** flush all the cached display list which need to be deleted + + /** Flush all the cached display list which need to be deleted * in the OpenGL context related to contextID.*/ static void flushAllDeletedDisplayLists(unsigned int contextID); - /** flush the cached display list which need to be deleted + /** Flush the cached display list which need to be deleted * in the OpenGL context related to contextID.*/ static void flushDeletedDisplayLists(unsigned int contextID,double& availableTime); - /** use deleteVertexBufferObject instead of glDeleteList to allow + /** Use deleteVertexBufferObject instead of glDeleteList to allow * OpenGL buffer objects to be cached until they can be deleted * by the OpenGL context in which they were created, specified * by contextID.*/ static void deleteVertexBufferObject(unsigned int contextID,GLuint globj); - - /** flush all the cached vertex buffer objects which need to be deleted + + /** Flush all the cached vertex buffer objects which need to be deleted * in the OpenGL context related to contextID.*/ static void flushDeletedVertexBufferObjects(unsigned int contextID,double currentTime, double& availableTime); typedef unsigned int AttributeType; - + enum AttributeTypes { VERTICES = 0, @@ -407,17 +426,16 @@ class SG_EXPORT Drawable : public Object TEXTURE_COORDS_4 = TEXTURE_COORDS_0+4, TEXTURE_COORDS_5 = TEXTURE_COORDS_0+5, TEXTURE_COORDS_6 = TEXTURE_COORDS_0+6, - TEXTURE_COORDS_7 = TEXTURE_COORDS_0+7 + TEXTURE_COORDS_7 = TEXTURE_COORDS_0+7 // only eight texture coord examples provided here, but underlying code can handle any no of texure units, // simply co them as (TEXTURE_COORDS_0+unit). }; - + class AttributeFunctor { public: - virtual ~AttributeFunctor() {} - + virtual void apply(AttributeType,unsigned int,GLbyte*) {} virtual void apply(AttributeType,unsigned int,GLshort*) {} virtual void apply(AttributeType,unsigned int,GLint*) {} @@ -432,23 +450,23 @@ class SG_EXPORT Drawable : public Object virtual void apply(AttributeType,unsigned int,Vec4*) {} virtual void apply(AttributeType,unsigned int,UByte4*) {} }; - - - /** return true if the Drawable subclass supports accept(AttributeFunctor&).*/ + + + /** Return true if the Drawable subclass supports accept(AttributeFunctor&).*/ virtual bool supports(AttributeFunctor&) const { return false; } /** accept an AttributeFunctor and call its methods to tell it about the internal attributes that this Drawable has. - * return true if functor handled by drawable, + * return true if functor handled by drawable, * return false on failure of drawable to generate functor calls.*/ virtual void accept(AttributeFunctor&) {} - + class ConstAttributeFunctor { public: - + virtual ~ConstAttributeFunctor() {} - + virtual void apply(AttributeType,const unsigned int,const GLbyte*) {} virtual void apply(AttributeType,const unsigned int,const GLshort*) {} virtual void apply(AttributeType,const unsigned int,const GLint*) {} @@ -464,11 +482,11 @@ class SG_EXPORT Drawable : public Object virtual void apply(AttributeType,const unsigned int,const UByte4*) {} }; - /** return true if the Drawable subclass supports accept(ConstAttributeFunctor&).*/ + /** Return true if the Drawable subclass supports accept(ConstAttributeFunctor&).*/ virtual bool supports(ConstAttributeFunctor&) const { return false; } - /** accept an AttributeFunctor and call its methods to tell it about the internal attributes that this Drawable has. - * return true if functor handled by drawable, + /** Accept an AttributeFunctor and call its methods to tell it about the internal attributes that this Drawable has. + * return true if functor handled by drawable, * return false on failure of drawable to generate functor calls.*/ virtual void accept(ConstAttributeFunctor&) const {} @@ -476,18 +494,18 @@ class SG_EXPORT Drawable : public Object class PrimitiveFunctor { public: - + virtual ~PrimitiveFunctor() {} virtual void setVertexArray(unsigned int count,const Vec2* vertices) = 0; virtual void setVertexArray(unsigned int count,const Vec3* vertices) = 0; virtual void setVertexArray(unsigned int count,const Vec4* vertices) = 0; - + virtual void drawArrays(GLenum mode,GLint first,GLsizei count) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLubyte* indices) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLushort* indices) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLuint* indices) = 0; - + virtual void begin(GLenum mode) = 0; virtual void vertex(const Vec2& vert) = 0; virtual void vertex(const Vec3& vert) = 0; @@ -496,43 +514,41 @@ class SG_EXPORT Drawable : public Object virtual void vertex(float x,float y,float z) = 0; virtual void vertex(float x,float y,float z,float w) = 0; virtual void end() = 0; - }; - + class PrimitiveIndexFunctor { public: - + virtual ~PrimitiveIndexFunctor() {} virtual void setVertexArray(unsigned int count,const Vec2* vertices) = 0; virtual void setVertexArray(unsigned int count,const Vec3* vertices) = 0; virtual void setVertexArray(unsigned int count,const Vec4* vertices) = 0; - + virtual void drawArrays(GLenum mode,GLint first,GLsizei count) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLubyte* indices) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLushort* indices) = 0; virtual void drawElements(GLenum mode,GLsizei count,const GLuint* indices) = 0; - + virtual void begin(GLenum mode) = 0; virtual void vertex(unsigned int pos) = 0; virtual void end() = 0; - }; - /** return true if the Drawable subclass supports accept(PrimitiveFunctor&).*/ + /** Return true if the Drawable subclass supports accept(PrimitiveFunctor&).*/ virtual bool supports(PrimitiveFunctor&) const { return false; } - /** accept a PrimitiveFunctor and call its methods to tell it about the internal primitives that this Drawable has. + /** Accept a PrimitiveFunctor and call its methods to tell it about the internal primitives that this Drawable has. * return true if functor handled by drawable, return false on failure of drawable to generate functor calls. * Note, PrimtiveFunctor only provides const access of the primitives, as primitives may be procedurally generated * so one cannot modify it.*/ virtual void accept(PrimitiveFunctor&) const {} - /** return true if the Drawable subclass supports accept(PrimitiveIndexFunctor&).*/ + /** Return true if the Drawable subclass supports accept(PrimitiveIndexFunctor&).*/ virtual bool supports(PrimitiveIndexFunctor&) const { return false; } - /** accept a PrimitiveIndexFunctor and call its methods to tell it about the internal primitives that this Drawable has. + /** Accept a PrimitiveIndexFunctor and call its methods to tell it about the internal primitives that this Drawable has. * return true if functor handled by drawable, return false on failure of drawable to generate functor calls. * Note, PrimtiveIndexFunctor only provide const access of the primitives, as primitives may be procedurally generated * so one cannot modify it.*/ @@ -540,8 +556,8 @@ class SG_EXPORT Drawable : public Object /** Extensions class which encapsulates the querying of extensions and - * associated function pointers, and provide convenience wrappers to - * check for the extensions or use the associated functions.*/ + * associated function pointers, and provide convenience wrappers to + * check for the extensions or use the associated functions.*/ class SG_EXPORT Extensions : public osg::Referenced { public: @@ -721,13 +737,13 @@ class SG_EXPORT Drawable : public Object virtual ~Drawable(); - /** compute the bounding box of the drawable. Method must be + /** Compute the bounding box of the drawable. Method must be implemented by subclasses.*/ virtual bool computeBound() const; - + /** set the bounding box .*/ void setBound(const BoundingBox& bb) const; - + void addParent(osg::Node* node); void removeParent(osg::Node* node); @@ -739,7 +755,7 @@ class SG_EXPORT Drawable : public Object mutable BoundingBox _bbox; mutable bool _bbox_computed; - + ref_ptr _shape; bool _supportsDisplayList; @@ -754,15 +770,13 @@ class SG_EXPORT Drawable : public Object ref_ptr _updateCallback; ref_ptr _cullCallback; ref_ptr _drawCallback; - - }; inline void Drawable::draw(State& state) const { if (_useDisplayList && !(_supportsVertexBufferObjects && _useVertexBufferObjects && state.isVertexBufferObjectSupported())) { - // get the contextID (user defined ID of 0 upwards) for the + // get the contextID (user defined ID of 0 upwards) for the // current OpenGL context. unsigned int contextID = state.getContextID(); @@ -781,22 +795,22 @@ inline void Drawable::draw(State& state) const glNewList( globj, GL_COMPILE ); if (_drawCallback.valid()) _drawCallback->drawImplementation(state,this); - else + else drawImplementation(state); glEndList(); - + glCallList( globj); #else globj = generateDisplayList(contextID, getGLObjectSizeHint()); glNewList( globj, GL_COMPILE_AND_EXECUTE ); if (_drawCallback.valid()) _drawCallback->drawImplementation(state,this); - else - drawImplementation(state); + else + drawImplementation(state); glEndList(); #endif } - + return; } @@ -804,7 +818,7 @@ inline void Drawable::draw(State& state) const // draw object as nature intended.. if (_drawCallback.valid()) _drawCallback->drawImplementation(state,this); - else + else drawImplementation(state); }; diff --git a/include/osg/Geode b/include/osg/Geode index 45c73f68c..89dc81fa2 100644 --- a/include/osg/Geode +++ b/include/osg/Geode @@ -1,13 +1,13 @@ -/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield +/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield * - * This library is open source and may be redistributed and/or modified under - * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or + * This library is open source and may be redistributed and/or modified under + * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or * (at your option) any later version. The full license is in LICENSE file * included with this distribution, and on the openscenegraph.org website. - * + * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * OpenSceneGraph Public License for more details. */ @@ -20,7 +20,11 @@ namespace osg { -/** Leaf Node for grouping Drawables.*/ +/** A \c Geode is a "geometry node", that is, a leaf node on the scene graph + * that can have "renderable things" attached to it. In OSG, renderable things + * are represented by objects from the \c Drawable class, so a \c Geode is a + * \c Node whose purpose is grouping Drawables. +*/ class SG_EXPORT Geode : public Node { public: @@ -34,51 +38,66 @@ class SG_EXPORT Geode : public Node META_Node(osg, Geode); - /** Add Drawable to Geode. - * If drawable is not NULL and is not contained in Geode then increment its - * reference count, add it to the drawables list and dirty the bounding - * sphere to force it to recompute on next getBound() and return true for success. - * Otherwise return false. - */ + /** Add a \c Drawable to the \c Geode. + * If \c drawable is not \c NULL and is not contained in the \c Geode + * then increment its reference count, add it to the drawables list and + * dirty the bounding sphere to force it to be recomputed on the next + * call to \c getBound(). + * @param drawable The \c Drawable to be added to the \c Geode. + * @return \c true for success; \c false otherwise. + */ virtual bool addDrawable( Drawable *drawable ); - /** Remove Drawable from Geode. - * Equivalent to setDrawable(getDrawableIndex(originChild),node), - * see docs for setNode for further details on implementation.*/ + /** Remove a \c Drawable from the \c Geode. + * Equivalent to removeDrawable(getDrawableIndex(drawable). + * @param drawable The drawable to be removed. + * @return \c true if at least one \c Drawable was removed. \c false + * otherwise. + */ virtual bool removeDrawable( Drawable *drawable ); - /** Remove drawable(s) from the specified position in Geode's drawable list.*/ + /** Remove Drawable(s) from the specified position in + * Geode's drawable list. + * @param i The index of the first \c Drawable to remove. + * @param numDrawablesToRemove The number of Drawable to + * remove. + * @return \c true if at least one \c Drawable was removed. \c false + * otherwise. + */ virtual bool removeDrawable(unsigned int i,unsigned int numDrawablesToRemove=1); /** Replace specified Drawable with another Drawable. - * Equivalent to setDrawable(getDrawableIndex(originChild),node), - * see docs for setDrawable for further details on implementation.*/ + * Equivalent to setDrawable(getDrawableIndex(origDraw),newDraw), + * see docs for \c setDrawable() for further details on implementation. + */ virtual bool replaceDrawable( Drawable *origDraw, Drawable *newDraw ); - /** set drawable at position i. - * return true if set correctly, false on failure (if node==NULL || i is out of range). - * Decrement the reference count origGSet and increments the - * reference count of newGset, and dirty the bounding sphere - * to force it to recompute on next getBound() and returns true. - * If origDrawable is not found then return false and do not - * add newGset. If newGset is NULL then return false and do - * not remove origGset. - */ + /** Set \c Drawable at position \c i. + * Decrement the reference count origGSet and increments the + * reference count of newGset, and dirty the bounding sphere + * to force it to recompute on next getBound() and returns true. + * If origDrawable is not found then return false and do not + * add newGset. If newGset is NULL then return false and do + * not remove origGset. + * @return \c true if set correctly, \c false on failure + * (if node==NULL || i is out of range). + */ virtual bool setDrawable( unsigned int i, Drawable* drawable ); - /** return the number of drawables.*/ + /** Return the number of Drawables currently attached to the + * \c Geode. + */ inline unsigned int getNumDrawables() const { return _drawables.size(); } - /** return drawable at position i.*/ + /** Return the \c Drawable at position \c i.*/ inline Drawable* getDrawable( unsigned int i ) { return _drawables[i].get(); } - /** return drawable at position i.*/ + /** Return the \c Drawable at position \c i.*/ inline const Drawable* getDrawable( unsigned int i ) const { return _drawables[i].get(); } - /** return true if drawable is contained within Geode.*/ + /** Return \c true if a given \c Drawable is contained within \c Geode.*/ inline bool containsDrawable(const Drawable* gset) const { - for (DrawableList::const_iterator itr=_drawables.begin(); itr!=_drawables.end(); ++itr) @@ -88,29 +107,31 @@ class SG_EXPORT Geode : public Node return false; } - /** Get the index number of drawable, return a value between - * 0 and _drawables.size()-1 if found, if not found then - * return _drawables.size().*/ - inline unsigned int getDrawableIndex( const Drawable* node ) const + /** Get the index number of \c drawable. + * @return A value between 0 and getNumDrawables()-1 if + * \c drawable is found; if not found, then + * getNumDrawables() is returned. + */ + inline unsigned int getDrawableIndex( const Drawable* drawable ) const { for (unsigned int drawableNum=0;drawableNum<_drawables.size();++drawableNum) { - if (_drawables[drawableNum]==node) return drawableNum; + if (_drawables[drawableNum]==drawable) return drawableNum; } - return _drawables.size(); // node not found. + return _drawables.size(); // drawable not found. } - /** compile OpenGL Display List for each drawable.*/ + /** Compile OpenGL Display List for each drawable.*/ void compileDrawables(State& state); - - /** return the Geode's bounding box, which is the union of all the + + /** Return the Geode's bounding box, which is the union of all the * bounding boxes of the geode's drawables.*/ inline const BoundingBox& getBoundingBox() const { if(!_bsphere_computed) computeBound(); return _bbox; } - + protected: virtual ~Geode(); diff --git a/include/osg/ShapeDrawable b/include/osg/ShapeDrawable index e4fb2a812..cc60a105d 100644 --- a/include/osg/ShapeDrawable +++ b/include/osg/ShapeDrawable @@ -1,13 +1,13 @@ -/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield +/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield * - * This library is open source and may be redistributed and/or modified under - * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or + * This library is open source and may be redistributed and/or modified under + * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or * (at your option) any later version. The full license is in LICENSE file * included with this distribution, and on the openscenegraph.org website. - * + * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * OpenSceneGraph Public License for more details. */ @@ -23,145 +23,158 @@ namespace osg { +/** Describe several hints that can be passed to a tesselator (like the one used + * by \c ShapeDrawable) as a mean to try to influence the way it works. + */ class TessellationHints : public Object { public: - TessellationHints(): - _TessellationMode(USE_SHAPE_DEFAULTS), - _detailRatio(1.0f), - _targetNumFaces(100), - _createFrontFace(true), - _createBackFace(false), - _createNormals(true), - _createTextureCoords(false), - _createTop(true), - _createBody(true), - _createBottom(true) {} - + TessellationHints(): + _TessellationMode(USE_SHAPE_DEFAULTS), + _detailRatio(1.0f), + _targetNumFaces(100), + _createFrontFace(true), + _createBackFace(false), + _createNormals(true), + _createTextureCoords(false), + _createTop(true), + _createBody(true), + _createBottom(true) {} - TessellationHints(const TessellationHints& tess, const CopyOp& copyop=CopyOp::SHALLOW_COPY): - Object(tess,copyop), - _TessellationMode(tess._TessellationMode), + + TessellationHints(const TessellationHints& tess, const CopyOp& copyop=CopyOp::SHALLOW_COPY): + Object(tess,copyop), + _TessellationMode(tess._TessellationMode), _detailRatio(tess._detailRatio), - _targetNumFaces(tess._targetNumFaces), - _createFrontFace(tess._createFrontFace), - _createBackFace(tess._createBackFace), - _createNormals(tess._createNormals), - _createTextureCoords(tess._createTextureCoords), - _createTop(tess._createTop), - _createBody(tess._createBody), - _createBottom(tess._createBottom) {} + _targetNumFaces(tess._targetNumFaces), + _createFrontFace(tess._createFrontFace), + _createBackFace(tess._createBackFace), + _createNormals(tess._createNormals), + _createTextureCoords(tess._createTextureCoords), + _createTop(tess._createTop), + _createBody(tess._createBody), + _createBottom(tess._createBottom) {} - META_Object(osg,TessellationHints); - - - enum TessellationMode - { - USE_SHAPE_DEFAULTS, - USE_TARGET_NUM_FACES - }; + META_Object(osg,TessellationHints); - inline void setTessellationMode(TessellationMode mode) { _TessellationMode=mode; } - inline TessellationMode getTessellationMode() const { return _TessellationMode; } + + enum TessellationMode + { + USE_SHAPE_DEFAULTS, + USE_TARGET_NUM_FACES + }; + + inline void setTessellationMode(TessellationMode mode) { _TessellationMode=mode; } + inline TessellationMode getTessellationMode() const { return _TessellationMode; } inline void setDetailRatio(float ratio) { _detailRatio = ratio; } inline float getDetailRatio() const { return _detailRatio; } - inline void setTargetNumFaces(unsigned int target) { _targetNumFaces=target; } - inline unsigned int getTargetNumFaces() const { return _targetNumFaces; } + inline void setTargetNumFaces(unsigned int target) { _targetNumFaces=target; } + inline unsigned int getTargetNumFaces() const { return _targetNumFaces; } - inline void setCreateFrontFace(bool on) { _createFrontFace=on; } - inline bool getCreateFrontFace() const { return _createFrontFace; } + inline void setCreateFrontFace(bool on) { _createFrontFace=on; } + inline bool getCreateFrontFace() const { return _createFrontFace; } - inline void setCreateBackFace(bool on) { _createBackFace=on; } - inline bool getCreateBackFace() const { return _createBackFace; } + inline void setCreateBackFace(bool on) { _createBackFace=on; } + inline bool getCreateBackFace() const { return _createBackFace; } - inline void setCreateNormals(bool on) { _createNormals=on; } - inline bool getCreateNormals() const { return _createNormals; } + inline void setCreateNormals(bool on) { _createNormals=on; } + inline bool getCreateNormals() const { return _createNormals; } - inline void setCreateTextureCoords(bool on) { _createTextureCoords=on; } - inline bool getCreateTextureCoords() const { return _createTextureCoords; } + inline void setCreateTextureCoords(bool on) { _createTextureCoords=on; } + inline bool getCreateTextureCoords() const { return _createTextureCoords; } - inline void setCreateTop(bool on) { _createTop=on; } - inline bool getCreateTop() const { return _createTop; } + inline void setCreateTop(bool on) { _createTop=on; } + inline bool getCreateTop() const { return _createTop; } - inline void setCreateBody(bool on) { _createBody=on; } - inline bool getCreateBody() const { return _createBody; } + inline void setCreateBody(bool on) { _createBody=on; } + inline bool getCreateBody() const { return _createBody; } - inline void setCreateBottom(bool on) { _createBottom=on; } - inline bool getCreateBottom() const { return _createBottom; } + inline void setCreateBottom(bool on) { _createBottom=on; } + inline bool getCreateBottom() const { return _createBottom; } protected: - - ~TessellationHints() {} - - TessellationMode _TessellationMode; + ~TessellationHints() {} + + + TessellationMode _TessellationMode; float _detailRatio; - unsigned int _targetNumFaces; + unsigned int _targetNumFaces; - bool _createFrontFace; - bool _createBackFace; - bool _createNormals; - bool _createTextureCoords; + bool _createFrontFace; + bool _createBackFace; + bool _createNormals; + bool _createTextureCoords; - bool _createTop; - bool _createBody; - bool _createBottom; + bool _createTop; + bool _createBody; + bool _createBottom; }; + +/** Allow the use of Shapes as Drawables, so that they can + * be rendered with reduced effort. The implementation of \c ShapeDrawable is + * not geared to efficiency; it's better to think of it as a convenience to + * render Shapes easily (perhaps for test or debugging purposes) than + * as the right way to render basic shapes in some efficiency-critical section + * of code. + * @todo \c ShapeDrawable currently doesn't render InfinitePlanes. + */ class SG_EXPORT ShapeDrawable : public Drawable { public: ShapeDrawable(); - ShapeDrawable(Shape* shape,TessellationHints* hints=0); + ShapeDrawable(Shape* shape, TessellationHints* hints=0); /** Copy constructor using CopyOp to manage deep vs shallow copy.*/ ShapeDrawable(const ShapeDrawable& pg,const CopyOp& copyop=CopyOp::SHALLOW_COPY); - + virtual Object* cloneType() const { return new ShapeDrawable(); } - virtual Object* clone(const CopyOp& copyop) const { return new ShapeDrawable(*this,copyop); } + virtual Object* clone(const CopyOp& copyop) const { return new ShapeDrawable(*this,copyop); } virtual bool isSameKindAs(const Object* obj) const { return dynamic_cast(obj)!=NULL; } virtual const char* libraryName() const { return "osg"; } virtual const char* className() const { return "ShapeDrawable"; } - /** set the color of the shape.*/ + /** Set the color of the shape.*/ void setColor(const Vec4& color) { _color = color; } - - /** get the color of the shape.*/ + + /** Get the color of the shape.*/ const Vec4& getColor() const { return _color; } - void setTessellationHints(TessellationHints* hints) { _tessellationHints = hints; } - - TessellationHints* getTessellationHints() { return _tessellationHints.get(); } - const TessellationHints* getTessellationHints() const { return _tessellationHints.get(); } + void setTessellationHints(TessellationHints* hints) { _tessellationHints = hints; } + + TessellationHints* getTessellationHints() { return _tessellationHints.get(); } + const TessellationHints* getTessellationHints() const { return _tessellationHints.get(); } - /** draw ShapeDrawable directly ignoring an OpenGL display list which could be attached. - * This is the internal draw method which does the drawing itself, - * and is the method to override when deriving from ShapeDrawable for user-drawn objects. - */ + /** Draw ShapeDrawable directly ignoring an OpenGL display list which + * could be attached. This is the internal draw method which does the + * drawing itself, and is the method to override when deriving from + * ShapeDrawable for user-drawn objects. + */ virtual void drawImplementation(State& state) const; - /** return false, osg::ShapeDrawable does not support accept(AttributeFunctor&).*/ + /** Return false, osg::ShapeDrawable does not support accept(AttributeFunctor&).*/ virtual bool supports(AttributeFunctor&) const { return false; } - /** return true, osg::ShapeDrawable does support accept(ConstAttributeFunctor&).*/ + /** Return true, osg::ShapeDrawable does support accept(ConstAttributeFunctor&).*/ virtual bool supports(ConstAttributeFunctor&) const { return true; } - /** accept a ConstAttributeFunctor and call its methods to tell it about the interal attributes that this Drawable has.*/ + /** Accept a ConstAttributeFunctor and call its methods to tell it about the interal attributes that this Drawable has.*/ virtual void accept(ConstAttributeFunctor& af) const; - /** return true, osg::ShapeDrawable does support accept(PrimitiveFunctor&) .*/ + /** Return true, osg::ShapeDrawable does support accept(PrimitiveFunctor&) .*/ virtual bool supports(PrimitiveFunctor&) const { return true; } - /** accept a PrimtiveFunctor and call its methods to tell it about the internal primitives that this Drawable has.*/ + /** Accept a PrimitiveFunctor and call its methods to tell it about the internal primitives that this Drawable has.*/ virtual void accept(PrimitiveFunctor& pf) const; protected: @@ -169,12 +182,12 @@ class SG_EXPORT ShapeDrawable : public Drawable ShapeDrawable& operator = (const ShapeDrawable&) { return *this;} virtual ~ShapeDrawable(); - + virtual bool computeBound() const; - + Vec4 _color; - ref_ptr _tessellationHints; + ref_ptr _tessellationHints; };