FGFS-4.1/OpenSceneGraph
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

From Leandro Motta Barros, doxygen comments

Browse Source
This commit is contained in:
Robert Osfield 2005-01-27 13:15:21 +00:00
parent 75175ecb48
commit 7e75997db0
3 changed files with 278 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
include/osg/Drawable
View File

@ -107,11 +107,22 @@ class Geometry;
#define USE_SEPARATE_COMPILE_AND_EXECUTE #define USE_SEPARATE_COMPILE_AND_EXECUTE
/** Pure virtual base class for drawable Geometry. Contains no drawing primitives /** Pure virtual base class for drawable geometry. In OSG, everything that can
directly, these are provided by subclasses such as osg::Geometry. State attributes * be rendered is implemented as a class derived from \c Drawable. The
for a Drawable are maintained in StateSet which the Drawable maintains * \c Drawable class contains no drawing primitives, since these are provided
a referenced counted pointer to. Both Drawable's and StateSet's can * by subclasses such as \c osg::Geometry.
be shared for optimal memory usage and graphics performance. * <p>Notice that a \c Drawable is not a \c Node, and therefore it cannot be
* directly added to a scene graph. Instead, <tt>Drawable</tt>s are attached to
* <tt>Geode</tt>s, which are scene graph nodes.
* <p>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, <tt>StateSet</tt>s can be shared between
* different <tt>Drawable</tt>s. In fact, sharing <tt>StateSet</tt>s is a good
* way to improve performance, since this allows OSG to reduce the number of
* expensive changes in the OpenGL state.
* <p>Finally, <tt>Drawable</tt>s can also be shared between different
* <tt>Geode</tt>s, 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 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* libraryName() const { return "osg"; }
virtual const char* className() const { return "Drawable"; } 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<Geometry*>(this).*/ * Equivalent to dynamic_cast<Geometry*>(this).*/
virtual Geometry* asGeometry() { return 0; } 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<const Geometry*>(this).*/ * Equivalent to dynamic_cast<const Geometry*>(this).*/
virtual const Geometry* asGeometry() const { return 0; } virtual const Geometry* asGeometry() const { return 0; }
@ -201,9 +212,11 @@ class SG_EXPORT Drawable : public Object
} }
/** Set the Shape of the drawable. The shape can be used to /** Set the Shape of the \c Drawable. The shape can be used to
* speed up collision detection or as a guide for procedural * speed up collision detection or as a guide for procedural
* geometry generation - see osg::Shape.*/ * geometry generation.
* @see osg::Shape.
*/
inline void setShape(Shape* shape) { _shape = shape; } inline void setShape(Shape* shape) { _shape = shape; }
/** Get the Shape of the Drawable.*/ /** Get the Shape of the Drawable.*/
@ -253,18 +266,22 @@ class SG_EXPORT Drawable : public Object
/** draw OpenGL primitives. /** Draw OpenGL primitives.
* If the drawable has _useDisplayList set to true then use an OpenGL display * If the \c Drawable has \c _useDisplayList set to \c true, then use
* list, automatically compiling one if required. * an OpenGL display list, automatically compiling one if required.
* Otherwise call drawImplementation(). * Otherwise, call \c drawImplementation().
* Note, draw method should *not* be overridden in subclasses as it * @note This method should \e not be overridden in subclasses, as it
* manages the optional display list. * manages the optional display list (notice this is not even
* \c virtual). Subclasses should override
* \c drawImplementation() instead.
*/ */
inline void draw(State& state) const; inline void draw(State& state) const;
/** Immediately compile this drawable into an OpenGL Display List. /** Immediately compile this \c Drawable into an OpenGL Display List.
Note I, operation is ignored if _useDisplayList to false. * @note Operation is ignored if \c _useDisplayList is \c false.
Note II, compile is not intended to be overridden in subclasses.*/ * @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; virtual void compileGLObjects(State& state) const;
/** /**
@ -347,9 +364,11 @@ class SG_EXPORT Drawable : public Object
/** draw directly ignoring an OpenGL display list which could be attached. /** Draw the \c Geometry "directly", that is, by issuing all the OpenGL
* This is the internal draw method which does the drawing itself, * calls needed to draw it. Contrast this with \c draw(), that can
* and is the method to override when deriving from Drawable. * compile and use an OpenGL display list to do the rendering.
* <p> 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; virtual void drawImplementation(State& state) const = 0;
@ -363,27 +382,27 @@ class SG_EXPORT Drawable : public Object
/** Get the minimum number of display lists to retain in the deleted display list cache. */ /** Get the minimum number of display lists to retain in the deleted display list cache. */
static unsigned int getMinimumNumberOfDisplayListsToRetainInCache(); 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 * OpenGL display list to be cached until they can be deleted
* by the OpenGL context in which they were created, specified * by the OpenGL context in which they were created, specified
* by contextID.*/ * by contextID.*/
static void deleteDisplayList(unsigned int contextID,GLuint globj, unsigned int sizeHint = 0); 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.*/ * in the OpenGL context related to contextID.*/
static void flushAllDeletedDisplayLists(unsigned int 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.*/ * in the OpenGL context related to contextID.*/
static void flushDeletedDisplayLists(unsigned int contextID,double& availableTime); 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 * OpenGL buffer objects to be cached until they can be deleted
* by the OpenGL context in which they were created, specified * by the OpenGL context in which they were created, specified
* by contextID.*/ * by contextID.*/
static void deleteVertexBufferObject(unsigned int contextID,GLuint globj); 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.*/ * in the OpenGL context related to contextID.*/
static void flushDeletedVertexBufferObjects(unsigned int contextID,double currentTime, double& availableTime); static void flushDeletedVertexBufferObjects(unsigned int contextID,double currentTime, double& availableTime);
@ -415,7 +434,6 @@ class SG_EXPORT Drawable : public Object
class AttributeFunctor class AttributeFunctor
{ {
public: public:
virtual ~AttributeFunctor() {} virtual ~AttributeFunctor() {}
virtual void apply(AttributeType,unsigned int,GLbyte*) {} virtual void apply(AttributeType,unsigned int,GLbyte*) {}
@ -434,7 +452,7 @@ class SG_EXPORT Drawable : public Object
}; };
/** 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; } 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. /** accept an AttributeFunctor and call its methods to tell it about the internal attributes that this Drawable has.
@ -464,10 +482,10 @@ class SG_EXPORT Drawable : public Object
virtual void apply(AttributeType,const unsigned int,const UByte4*) {} 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; } 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. /** 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.*/ * return false on failure of drawable to generate functor calls.*/
virtual void accept(ConstAttributeFunctor&) const {} virtual void accept(ConstAttributeFunctor&) const {}
@ -496,7 +514,6 @@ 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) = 0;
virtual void vertex(float x,float y,float z,float w) = 0; virtual void vertex(float x,float y,float z,float w) = 0;
virtual void end() = 0; virtual void end() = 0;
}; };
class PrimitiveIndexFunctor class PrimitiveIndexFunctor
@ -517,22 +534,21 @@ class SG_EXPORT Drawable : public Object
virtual void begin(GLenum mode) = 0; virtual void begin(GLenum mode) = 0;
virtual void vertex(unsigned int pos) = 0; virtual void vertex(unsigned int pos) = 0;
virtual void end() = 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; } 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. * 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 * Note, PrimtiveFunctor only provides const access of the primitives, as primitives may be procedurally generated
* so one cannot modify it.*/ * so one cannot modify it.*/
virtual void accept(PrimitiveFunctor&) const {} 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; } 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. * 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 * Note, PrimtiveIndexFunctor only provide const access of the primitives, as primitives may be procedurally generated
* so one cannot modify it.*/ * so one cannot modify it.*/
@ -721,7 +737,7 @@ class SG_EXPORT Drawable : public Object
virtual ~Drawable(); 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.*/ implemented by subclasses.*/
virtual bool computeBound() const; virtual bool computeBound() const;
@ -754,8 +770,6 @@ class SG_EXPORT Drawable : public Object
ref_ptr<UpdateCallback> _updateCallback; ref_ptr<UpdateCallback> _updateCallback;
ref_ptr<CullCallback> _cullCallback; ref_ptr<CullCallback> _cullCallback;
ref_ptr<DrawCallback> _drawCallback; ref_ptr<DrawCallback> _drawCallback;
}; };
inline void Drawable::draw(State& state) const inline void Drawable::draw(State& state) const

75
include/osg/Geode
View File

@ -20,7 +20,11 @@
namespace osg { 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 <tt>Drawable</tt>s.
*/
class SG_EXPORT Geode : public Node class SG_EXPORT Geode : public Node
{ {
public: public:
@ -34,51 +38,66 @@ class SG_EXPORT Geode : public Node
META_Node(osg, Geode); META_Node(osg, Geode);
/** Add Drawable to Geode. /** Add a \c Drawable to the \c Geode.
* If drawable is not NULL and is not contained in Geode then increment its * If \c drawable is not \c NULL and is not contained in the \c Geode
* reference count, add it to the drawables list and dirty the bounding * then increment its reference count, add it to the drawables list and
* sphere to force it to recompute on next getBound() and return true for success. * dirty the bounding sphere to force it to be recomputed on the next
* Otherwise return false. * 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 ); virtual bool addDrawable( Drawable *drawable );
/** Remove Drawable from Geode. /** Remove a \c Drawable from the \c Geode.
* Equivalent to setDrawable(getDrawableIndex(originChild),node), * Equivalent to <tt>removeDrawable(getDrawableIndex(drawable)</tt>.
* see docs for setNode for further details on implementation.*/ * @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 ); virtual bool removeDrawable( Drawable *drawable );
/** Remove drawable(s) from the specified position in Geode's drawable list.*/ /** Remove <tt>Drawable</tt>(s) from the specified position in
* <tt>Geode</tt>'s drawable list.
* @param i The index of the first \c Drawable to remove.
* @param numDrawablesToRemove The number of <tt>Drawable</tt> 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); virtual bool removeDrawable(unsigned int i,unsigned int numDrawablesToRemove=1);
/** Replace specified Drawable with another Drawable. /** Replace specified Drawable with another Drawable.
* Equivalent to setDrawable(getDrawableIndex(originChild),node), * Equivalent to <tt>setDrawable(getDrawableIndex(origDraw),newDraw)</tt>,
* see docs for setDrawable for further details on implementation.*/ * see docs for \c setDrawable() for further details on implementation.
*/
virtual bool replaceDrawable( Drawable *origDraw, Drawable *newDraw ); virtual bool replaceDrawable( Drawable *origDraw, Drawable *newDraw );
/** set drawable at position i. /** Set \c Drawable at position \c 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 * Decrement the reference count origGSet and increments the
* reference count of newGset, and dirty the bounding sphere * reference count of newGset, and dirty the bounding sphere
* to force it to recompute on next getBound() and returns true. * to force it to recompute on next getBound() and returns true.
* If origDrawable is not found then return false and do not * If origDrawable is not found then return false and do not
* add newGset. If newGset is NULL then return false and do * add newGset. If newGset is NULL then return false and do
* not remove origGset. * 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 ); virtual bool setDrawable( unsigned int i, Drawable* drawable );
/** return the number of drawables.*/ /** Return the number of <tt>Drawable</tt>s currently attached to the
* \c Geode.
*/
inline unsigned int getNumDrawables() const { return _drawables.size(); } 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(); } 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(); } 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 inline bool containsDrawable(const Drawable* gset) const
{ {
for (DrawableList::const_iterator itr=_drawables.begin(); for (DrawableList::const_iterator itr=_drawables.begin();
itr!=_drawables.end(); itr!=_drawables.end();
++itr) ++itr)
@ -88,22 +107,24 @@ class SG_EXPORT Geode : public Node
return false; return false;
} }
/** Get the index number of drawable, return a value between /** Get the index number of \c drawable.
* 0 and _drawables.size()-1 if found, if not found then * @return A value between 0 and <tt>getNumDrawables()-1</tt> if
* return _drawables.size().*/ * \c drawable is found; if not found, then
inline unsigned int getDrawableIndex( const Drawable* node ) const * <tt>getNumDrawables()</tt> is returned.
*/
inline unsigned int getDrawableIndex( const Drawable* drawable ) const
{ {
for (unsigned int drawableNum=0;drawableNum<_drawables.size();++drawableNum) 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); 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.*/ * bounding boxes of the geode's drawables.*/
inline const BoundingBox& getBoundingBox() const inline const BoundingBox& getBoundingBox() const
{ {

35
include/osg/ShapeDrawable
View File

@ -23,6 +23,9 @@
namespace osg { 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 class TessellationHints : public Object
{ {
public: public:
@ -113,13 +116,22 @@ class TessellationHints : public Object
}; };
/** Allow the use of <tt>Shape</tt>s as <tt>Drawable</tt>s, 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 <tt>Shape</tt>s 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 <tt>InfinitePlane</tt>s.
*/
class SG_EXPORT ShapeDrawable : public Drawable class SG_EXPORT ShapeDrawable : public Drawable
{ {
public: public:
ShapeDrawable(); ShapeDrawable();
ShapeDrawable(Shape* shape,TessellationHints* hints=0); ShapeDrawable(Shape* shape, TessellationHints* hints=0);
/** Copy constructor using CopyOp to manage deep vs shallow copy.*/ /** Copy constructor using CopyOp to manage deep vs shallow copy.*/
ShapeDrawable(const ShapeDrawable& pg,const CopyOp& copyop=CopyOp::SHALLOW_COPY); ShapeDrawable(const ShapeDrawable& pg,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
@ -130,10 +142,10 @@ class SG_EXPORT ShapeDrawable : public Drawable
virtual const char* libraryName() const { return "osg"; } virtual const char* libraryName() const { return "osg"; }
virtual const char* className() const { return "ShapeDrawable"; } 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; } 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; } const Vec4& getColor() const { return _color; }
void setTessellationHints(TessellationHints* hints) { _tessellationHints = hints; } void setTessellationHints(TessellationHints* hints) { _tessellationHints = hints; }
@ -143,25 +155,26 @@ class SG_EXPORT ShapeDrawable : public Drawable
/** draw ShapeDrawable directly ignoring an OpenGL display list which could be attached. /** Draw ShapeDrawable directly ignoring an OpenGL display list which
* This is the internal draw method which does the drawing itself, * could be attached. This is the internal draw method which does the
* and is the method to override when deriving from ShapeDrawable for user-drawn objects. * drawing itself, and is the method to override when deriving from
* ShapeDrawable for user-drawn objects.
*/ */
virtual void drawImplementation(State& state) const; 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; } 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; } 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; 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; } 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; virtual void accept(PrimitiveFunctor& pf) const;
protected: protected: