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 
Ammendments by Robert Osfield, a few comment rewrites to better reflect API functionality/usage.
This commit is contained in:
Robert Osfield 2005-02-02 15:08:55 +00:00
parent ae0f93010f
commit b7bd8075de
3 changed files with 197 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
include/osg/Drawable
View File

@ -364,12 +364,11 @@ class SG_EXPORT Drawable : public Object
/** 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.
* <p> This is the internal draw method which does the drawing itself,
* and is the method to override when deriving from \c Drawable.
*/
/** drawImplementation(State&) is a pure virtaul method for the actual implementation of OpenGL drawing calls, such as vertex arrays and primitives, that
* must be implemented in concrete subclasses of the Drawable base class, examples include osg::Geometry and osg::ShapeDrawable.
* drawImplementation(State&) is called from the draw(State&) method, with the draw method handling management of OpenGL display lists,
* and drawImplementation(State&) handling the actuall drawing itself.
* @param state The osg::State object that encapulates the current OpenGL state for the current graphics context. */
virtual void drawImplementation(State& state) const = 0;

41
include/osg/State
View File

@ -60,8 +60,20 @@ namespace osg {
}\
}
/** State class for managing a state stack.
* Lazy state updating is used to minimize state changes.
/** Encapsulates the current applied OpenGL modes, attributes and vertex arrays settings,.
* implements lazy state updating and provides accessors for querrying the current state.
. The venerable Red Book says that "OpenGL is a state machine", and this class
* represents the OpenGL state in OSG. Furthermore, \c State also has other
* important features:
* - It works as a stack of states (see \c pushStateSet() and
* \c popStateSet()). Manipulating this stack of OpenGL states manually is
* seldom needed, since OSG does this is the most common situations.
* - It implements lazy state updating. This means that, if one requests a
* state change and that particular state is already in the requested stated, no OpenGL
* call will be made, this ensures that OpenGL pipeline is not stalled by unncessary state changes.
* - It allows to query the current OpenGL state without calls to \c glGet*(),
* which typically stall the graphics pipeline (see, for instance,
* \c captureCurrentState() and \c getModelViewMatrix()).
*/
class SG_EXPORT State : public Referenced
{
@ -149,7 +161,10 @@ class SG_EXPORT State : public Referenced
/** Apply stateset.*/
void apply(const StateSet* dstate);
/** Apply the state.*/
/** Updates the OpenGL state so that it matches the \c StateSet at the
* top of the stack of <tt>StateSet</tt>s maintained internally by a
* \c State.
*/
void apply();
@ -165,7 +180,15 @@ class SG_EXPORT State : public Referenced
}
/** Apply an OpenGL mode if required. */
/** Apply an OpenGL mode if required. This is a wrapper around
* \c glEnable() and \c glDisable(), that just actually calls these
* functions if the \c enabled flag is different than the current
* state.
* @return \c true if the state was actually changed. \c false
* otherwise. Notice that a \c false return does not indicate
* an error, it just means that the mode was already set to the
* same value as the \c enabled parameter.
*/
inline bool applyMode(StateAttribute::GLMode mode,bool enabled)
{
ModeStack& ms = _modeMap[mode];
@ -734,7 +757,15 @@ class SG_EXPORT State : public Referenced
};
/** apply an OpenGL mode if required, passing in mode, enable flag and appropriate mode stack */
/** Apply an OpenGL mode if required, passing in mode, enable flag and
* appropriate mode stack. This is a wrapper around \c glEnable() and
* \c glDisable(), that just actually calls these functions if the
* \c enabled flag is different than the current state.
* @return \c true if the state was actually changed. \c false
* otherwise. Notice that a \c false return does not indicate
* an error, it just means that the mode was already set to the
* same value as the \c enabled parameter.
*/
inline bool applyMode(StateAttribute::GLMode mode,bool enabled,ModeStack& ms)
{
if (ms.last_applied_value != enabled)

81
include/osg/StateSet
View File

@ -29,12 +29,14 @@
namespace osg {
/**
Encapsulates OpenGL state modes and attributes.
Used to specific textures etc of osg::Drawable's which hold references
to a single osg::StateSet. StateSet can be shared between Drawable's
and is recommend if possible as it minimizes expensive state changes
in the graphics pipeline.
/** Stores a set of modes and attributes which respresent a set of OpenGL state.
* Notice that a \c StateSet contains just a subset of the whole OpenGL state.
* <p>In OSG, each \c Drawable and each \c Node has a reference to a
* \c StateSet. These <tt>StateSet</tt>s can be shared between
* different <tt>Drawable</tt>s and <tt>Node</tt>s (that is, several
* <tt>Drawable</tt>s and <tt>Node</tt>s can reference the same \c StateSet).
* Indeed, this practice is recommended whenever possible,
* as this minimizes expensive state changes in the graphics pipeline.
*/
class SG_EXPORT StateSet : public Object
{
@ -70,14 +72,22 @@ class SG_EXPORT StateSet : public Object
/** Clear the StateSet of all modes and attributes.*/
void clear();
/** merge this stateset with stateset rhs, this overrides
* the rhs if OVERRIDE is specified, otherwise rhs takes precedence.*/
/** Merge this \c StateSet with the \c StateSet passed as parameter.
* Every mode and attribute in this \c StateSet that is marked with
* \c StateAttribute::OVERRIDE is replaced with the
* equivalent mode or attribute from \c rhs.
*/
void merge(const StateSet& rhs);
/** a container to map GLModes to their respective GLModeValues.*/
typedef std::map<StateAttribute::GLMode,StateAttribute::GLModeValue> ModeList;
/** Set this StateSet to contain specified GLMode and value.*/
/** Set this \c StateSet to contain the specified \c GLMode with a given
* value.
* @note Don't use this method to set modes related to textures. For this
* purpose, use \c setTextureMode(), that accepts an extra parameter
* specifying which texture unit shall be affected by the call.
*/
void setMode(StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
#ifdef USE_DEPRECATED_API
@ -85,20 +95,35 @@ class SG_EXPORT StateSet : public Object
* Has the effect of deleting any GLMode of specified type from StateSet.*/
void setModeToInherit(StateAttribute::GLMode mode) { removeMode(mode); }
#endif
/** Remove mode from StateSet.*/
/** Remove \c mode from this \c StateSet.
* @note Don't use this method to remove modes related to textures. For
* this purpose, use \c removeTextureMode(), that accepts an extra
* parameter specifying which texture unit shall be affected by
* the call.
*/
void removeMode(StateAttribute::GLMode mode);
/** Get specified GLModeValue for specified GLMode.
* returns INHERIT if no GLModeValue is contained within StateSet.*/
/** Get the value for a given \c GLMode.
* @param mode The \c GLMode whose value is desired.
* @return If \c mode is contained within this \c StateSet, returns the
* value associated with it. Otherwise, returns
* \c StateAttribute::INHERIT.
* @note Don't use this method to get the value of modes related to
* textures. For this purpose, use \c removeTextureMode(), that
* accepts an extra parameter specifying which texture unit shall
* be affected by the call.
*/
StateAttribute::GLModeValue getMode(StateAttribute::GLMode mode) const;
/** set the list of all GLModes contained in this StateSet.*/
/** Set the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
inline void setModeList(ModeList& ml) { _modeList=ml; }
/** return the list of all GLModes contained in this StateSet.*/
/** Return the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
inline ModeList& getModeList() { return _modeList; }
/** return the const list of all GLModes contained in this const StateSet.*/
/** Return the \c const list of all <tt>GLMode</tt>s contained in this
* <tt>const StateSet</tt>.
*/
inline const ModeList& getModeList() const { return _modeList; }
@ -151,7 +176,13 @@ class SG_EXPORT StateSet : public Object
typedef std::vector<ModeList> TextureModeList;
/** Set this StateSet to contain specified GLMode and value.*/
/** Set this \c StateSet to contain specified \c GLMode with a given
* value.
* @param unit The texture unit to be affected (used with
* multi-texturing).
* @param mode The OpenGL mode to be added to the \c StateSet.
* @param value The value to be assigned to \c mode.
*/
void setTextureMode(unsigned int unit,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
#ifdef USE_DEPRECATED_API
@ -228,14 +259,20 @@ class SG_EXPORT StateSet : public Object
TRANSPARENT_BIN = 2
};
/** Set the RenderingHint of the StateSet.
* RenderingHint is used by osgUtil::Renderer to determine which
* draw bin to drop associated osg::Drawables in. For opaque
* objects OPAQUE_BIN would typical used, which TRANSPARENT_BIN
* should be used for objects which need to be depth sorted.*/
/** Set the \c RenderingHint of this \c StateSet. \c RenderingHint is
* used by the renderer to determine which draw bin to drop associated
* <tt>osg::Drawable</tt>s in. Typically, users will set this to either
* \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN.
* <tt>Drawable</tt>s in the opaque bin are sorted by their
* \c StateSet, so that the number of expensive changes in the OpenGL
* state is minimized. <tt>Drawable</tt>s in the transparent bin are
* sorted by depth, so that objects farther from the viewer are
* rendered first (and hence alpha blending works nicely for
* translucent objects).
*/
void setRenderingHint(int hint);
/** Get the RenderingHint of the StateSet.*/
/** Get the \c RenderingHint of this \c StateSet.*/
inline int getRenderingHint() const { return _renderingHint; }
enum RenderBinMode