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

191
include/osg/State
View File

@ -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 * 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 * 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 * (at your option) any later version. The full license is in LICENSE file
* included with this distribution, and on the openscenegraph.org website. * included with this distribution, and on the openscenegraph.org website.
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * 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. * OpenSceneGraph Public License for more details.
*/ */
@ -48,7 +48,7 @@
namespace osg { namespace osg {
/** macro for use with osg::StateAttribute::apply methods for detecting and /** macro for use with osg::StateAttribute::apply methods for detecting and
* reporting OpenGL error messages.*/ * reporting OpenGL error messages.*/
#define OSG_GL_DEBUG(message) \ #define OSG_GL_DEBUG(message) \
if (state.getFineGrainedErrorDetection()) \ if (state.getFineGrainedErrorDetection()) \
@ -60,13 +60,25 @@ namespace osg {
}\ }\
} }
/** State class for managing a state stack. /** Encapsulates the current applied OpenGL modes, attributes and vertex arrays settings,.
* Lazy state updating is used to minimize state changes. * 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 class SG_EXPORT State : public Referenced
{ {
public : public :
State(); State();
/** Push stateset onto state stack.*/ /** Push stateset onto state stack.*/
@ -74,7 +86,7 @@ class SG_EXPORT State : public Referenced
/** Pop stateset off state stack.*/ /** Pop stateset off state stack.*/
void popStateSet(); void popStateSet();
/** pop all statesets off state stack, ensuring it is empty ready for the next frame. /** pop all statesets off state stack, ensuring it is empty ready for the next frame.
* Note, to return OpenGL to default state, one should do any state.popAllStatSets(); state.apply().*/ * Note, to return OpenGL to default state, one should do any state.popAllStatSets(); state.apply().*/
void popAllStateSets(); void popAllStateSets();
@ -84,12 +96,12 @@ class SG_EXPORT State : public Referenced
/** reset the state object to an empty stack.*/ /** reset the state object to an empty stack.*/
void reset(); void reset();
inline const Viewport* getCurrentViewport() const inline const Viewport* getCurrentViewport() const
{ {
return static_cast<const Viewport*>(getLastAppliedAttribute(osg::StateAttribute::VIEWPORT)); return static_cast<const Viewport*>(getLastAppliedAttribute(osg::StateAttribute::VIEWPORT));
} }
void setInitialViewMatrix(const osg::RefMatrix* matrix); void setInitialViewMatrix(const osg::RefMatrix* matrix);
@ -101,7 +113,7 @@ class SG_EXPORT State : public Referenced
if (_projection!=matrix) if (_projection!=matrix)
{ {
glMatrixMode( GL_PROJECTION ); glMatrixMode( GL_PROJECTION );
if (matrix) if (matrix)
{ {
_projection=matrix; _projection=matrix;
glLoadMatrix(matrix->ptr()); glLoadMatrix(matrix->ptr());
@ -114,7 +126,7 @@ class SG_EXPORT State : public Referenced
glMatrixMode( GL_MODELVIEW ); glMatrixMode( GL_MODELVIEW );
} }
} }
inline const osg::Matrix& getProjectionMatrix() const inline const osg::Matrix& getProjectionMatrix() const
{ {
return *_projection; return *_projection;
@ -129,7 +141,7 @@ class SG_EXPORT State : public Referenced
_modelView=matrix; _modelView=matrix;
glLoadMatrix(matrix->ptr()); glLoadMatrix(matrix->ptr());
} }
else else
{ {
_modelView=_identity; _modelView=_identity;
glLoadIdentity(); glLoadIdentity();
@ -149,7 +161,10 @@ class SG_EXPORT State : public Referenced
/** Apply stateset.*/ /** Apply stateset.*/
void apply(const StateSet* dstate); 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(); void apply();
@ -165,11 +180,19 @@ 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) inline bool applyMode(StateAttribute::GLMode mode,bool enabled)
{ {
ModeStack& ms = _modeMap[mode]; ModeStack& ms = _modeMap[mode];
ms.changed = true; ms.changed = true;
return applyMode(mode,enabled,ms); return applyMode(mode,enabled,ms);
} }
@ -247,10 +270,10 @@ class SG_EXPORT State : public Referenced
else else
return false; return false;
} }
/** Mode has been set externally, update state to reflect this setting.*/ /** Mode has been set externally, update state to reflect this setting.*/
void haveAppliedMode(StateAttribute::GLMode mode,StateAttribute::GLModeValue value); void haveAppliedMode(StateAttribute::GLMode mode,StateAttribute::GLModeValue value);
/** Mode has been set externally, therefore dirty the associated mode in osg::State /** Mode has been set externally, therefore dirty the associated mode in osg::State
* so it is applied on next call to osg::State::apply(..)*/ * so it is applied on next call to osg::State::apply(..)*/
void haveAppliedMode(StateAttribute::GLMode mode); void haveAppliedMode(StateAttribute::GLMode mode);
@ -269,13 +292,13 @@ class SG_EXPORT State : public Referenced
/** Get whether the current specified mode is enabled (true) or disabled (false).*/ /** Get whether the current specified mode is enabled (true) or disabled (false).*/
bool getLastAppliedMode(StateAttribute::GLMode mode) const; bool getLastAppliedMode(StateAttribute::GLMode mode) const;
/** Get the current specified attribute, return NULL if one has not yet been applied.*/ /** Get the current specified attribute, return NULL if one has not yet been applied.*/
const StateAttribute* getLastAppliedAttribute(StateAttribute::Type type, unsigned int member=0) const; const StateAttribute* getLastAppliedAttribute(StateAttribute::Type type, unsigned int member=0) const;
/** texture Mode has been set externally, update state to reflect this setting.*/ /** texture Mode has been set externally, update state to reflect this setting.*/
void haveAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode,StateAttribute::GLModeValue value); void haveAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode,StateAttribute::GLModeValue value);
/** texture Mode has been set externally, therefore dirty the associated mode in osg::State /** texture Mode has been set externally, therefore dirty the associated mode in osg::State
* so it is applied on next call to osg::State::apply(..)*/ * so it is applied on next call to osg::State::apply(..)*/
void haveAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode); void haveAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode);
@ -283,8 +306,8 @@ class SG_EXPORT State : public Referenced
/** texture Attribute has been applied externally, update state to reflect this setting.*/ /** texture Attribute has been applied externally, update state to reflect this setting.*/
void haveAppliedTextureAttribute(unsigned int unit, const StateAttribute* attribute); void haveAppliedTextureAttribute(unsigned int unit, const StateAttribute* attribute);
/** texture Attribute has been applied externally, /** texture Attribute has been applied externally,
* and therefore this attribute type has been dirtied * and therefore this attribute type has been dirtied
* and will need to be re-appplied on next osg::State.apply(..). * and will need to be re-appplied on next osg::State.apply(..).
* note, if you have an osg::StateAttribute which you have applied externally * note, if you have an osg::StateAttribute which you have applied externally
* then use the have_applied(attribute) method as this will the osg::State to * then use the have_applied(attribute) method as this will the osg::State to
@ -292,10 +315,10 @@ class SG_EXPORT State : public Referenced
* that only changed state will be applied.*/ * that only changed state will be applied.*/
void haveAppliedTextureAttribute(unsigned int unit, StateAttribute::Type type, unsigned int member=0); void haveAppliedTextureAttribute(unsigned int unit, StateAttribute::Type type, unsigned int member=0);
/** Get whether the current specified texture mode is enabled (true) or disabled (false).*/ /** Get whether the current specified texture mode is enabled (true) or disabled (false).*/
bool getLastAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode) const; bool getLastAppliedTextureMode(unsigned int unit, StateAttribute::GLMode mode) const;
/** Get the current specified texture attribute, return NULL if one has not yet been applied.*/ /** Get the current specified texture attribute, return NULL if one has not yet been applied.*/
const StateAttribute* getLastAppliedTextureAttribute(unsigned int unit, StateAttribute::Type type, unsigned int member=0) const; const StateAttribute* getLastAppliedTextureAttribute(unsigned int unit, StateAttribute::Type type, unsigned int member=0) const;
@ -335,7 +358,7 @@ class SG_EXPORT State : public Referenced
} }
_vertexArray._dirty = false; _vertexArray._dirty = false;
} }
/** wrapper around glDisableClientState(GL_VERTEX_ARRAY). /** wrapper around glDisableClientState(GL_VERTEX_ARRAY).
* note, only updates values that change.*/ * note, only updates values that change.*/
inline void disableVertexPointer() inline void disableVertexPointer()
@ -350,8 +373,8 @@ class SG_EXPORT State : public Referenced
inline void dirtyVertexPointer() inline void dirtyVertexPointer()
{ {
_vertexArray._pointer = 0; _vertexArray._pointer = 0;
_vertexArray._dirty = true; _vertexArray._dirty = true;
} }
/** wrapper around glEnableClientState(GL_NORMAL_ARRAY);glNormalPointer(..); /** wrapper around glEnableClientState(GL_NORMAL_ARRAY);glNormalPointer(..);
@ -421,7 +444,7 @@ class SG_EXPORT State : public Referenced
} }
inline void dirtyColorPointer() inline void dirtyColorPointer()
{ {
_colorArray._pointer = 0; _colorArray._pointer = 0;
_colorArray._dirty = true; _colorArray._dirty = true;
} }
@ -594,7 +617,7 @@ class SG_EXPORT State : public Referenced
} }
} }
/** Set the current tex coord array texture unit, return true if selected, /** Set the current tex coord array texture unit, return true if selected,
* false if selection failed such as when multitexturing is not supported. * false if selection failed such as when multitexturing is not supported.
* note, only updates values that change.*/ * note, only updates values that change.*/
bool setClientActiveTextureUnit( unsigned int unit ); bool setClientActiveTextureUnit( unsigned int unit );
@ -604,19 +627,19 @@ class SG_EXPORT State : public Referenced
* false if selection failed such as when multitexturing is not supported. * false if selection failed such as when multitexturing is not supported.
* note, only updates values that change.*/ * note, only updates values that change.*/
bool setActiveTextureUnit( unsigned int unit ); bool setActiveTextureUnit( unsigned int unit );
/** wrapper around glEnableVertexAttribArrayARB(index);glVertexAttribPointerARB(..); /** wrapper around glEnableVertexAttribArrayARB(index);glVertexAttribPointerARB(..);
* note, only updates values that change.*/ * note, only updates values that change.*/
void setVertexAttribPointer( unsigned int index, void setVertexAttribPointer( unsigned int index,
GLint size, GLenum type, GLboolean normalized, GLint size, GLenum type, GLboolean normalized,
GLsizei stride, const GLvoid *ptr ); GLsizei stride, const GLvoid *ptr );
/** wrapper around DisableVertexAttribArrayARB(index); /** wrapper around DisableVertexAttribArrayARB(index);
* note, only updates values that change.*/ * note, only updates values that change.*/
void disableVertexAttribPointer( unsigned int index ); void disableVertexAttribPointer( unsigned int index );
void disableVertexAttribPointersAboveAndIncluding( unsigned int index ); void disableVertexAttribPointersAboveAndIncluding( unsigned int index );
inline void dirtyVertexAttribPointersAboveAndIncluding( unsigned int index ) inline void dirtyVertexAttribPointersAboveAndIncluding( unsigned int index )
{ {
while (index<_vertexAttribArrayList.size()) while (index<_vertexAttribArrayList.size())
@ -640,37 +663,37 @@ class SG_EXPORT State : public Referenced
arrays that they maintain for the purpose. arrays that they maintain for the purpose.
Typical settings for contextID are 0,1,2,3... up to the maximum Typical settings for contextID are 0,1,2,3... up to the maximum
number of graphics contexts you have set up. number of graphics contexts you have set up.
By default contextID is 0.*/ By default contextID is 0.*/
inline void setContextID(unsigned int contextID) { _contextID=contextID; } inline void setContextID(unsigned int contextID) { _contextID=contextID; }
/** Get the current OpenGL context unique ID.*/ /** Get the current OpenGL context unique ID.*/
inline unsigned int getContextID() const { return _contextID; } inline unsigned int getContextID() const { return _contextID; }
/** Set the frame stamp for the current frame.*/ /** Set the frame stamp for the current frame.*/
inline void setFrameStamp(FrameStamp* fs) { _frameStamp = fs; } inline void setFrameStamp(FrameStamp* fs) { _frameStamp = fs; }
/** Get the frame stamp for the current frame.*/ /** Get the frame stamp for the current frame.*/
inline const FrameStamp* getFrameStamp() const { return _frameStamp.get(); } inline const FrameStamp* getFrameStamp() const { return _frameStamp.get(); }
/** Set the DisplaySettings. Note, nothing is applied, the visual settings are just /** Set the DisplaySettings. Note, nothing is applied, the visual settings are just
* used in the State object to pass the current visual settings to Drawables * used in the State object to pass the current visual settings to Drawables
* during rendering. */ * during rendering. */
inline void setDisplaySettings(DisplaySettings* vs) { _displaySettings = vs; } inline void setDisplaySettings(DisplaySettings* vs) { _displaySettings = vs; }
/** Get the DisplaySettings */ /** Get the DisplaySettings */
inline const DisplaySettings* getDisplaySettings() const { return _displaySettings.get(); } inline const DisplaySettings* getDisplaySettings() const { return _displaySettings.get(); }
typedef std::pair<const StateAttribute*,StateAttribute::OverrideValue> AttributePair; typedef std::pair<const StateAttribute*,StateAttribute::OverrideValue> AttributePair;
typedef std::vector<AttributePair> AttributeVec; typedef std::vector<AttributePair> AttributeVec;
typedef std::vector<StateAttribute::GLModeValue> ValueVec; typedef std::vector<StateAttribute::GLModeValue> ValueVec;
/** Set flag for early termination of the draw traversal.*/ /** Set flag for early termination of the draw traversal.*/
void setAbortRenderingPtr(bool* abortPtr) { _abortRenderingPtr = abortPtr; } void setAbortRenderingPtr(bool* abortPtr) { _abortRenderingPtr = abortPtr; }
/** Get flag for early termination of the draw traversal, /** Get flag for early termination of the draw traversal,
* if true steps should be taken to complete rendering early.*/ * if true steps should be taken to complete rendering early.*/
bool getAbortRendering() const { return _abortRenderingPtr!=0?(*_abortRenderingPtr):false; } bool getAbortRendering() const { return _abortRenderingPtr!=0?(*_abortRenderingPtr):false; }
@ -687,16 +710,16 @@ class SG_EXPORT State : public Referenced
unsigned int _contextID; unsigned int _contextID;
ref_ptr<FrameStamp> _frameStamp; ref_ptr<FrameStamp> _frameStamp;
ref_ptr<const RefMatrix> _identity; ref_ptr<const RefMatrix> _identity;
ref_ptr<const RefMatrix> _initialViewMatrix; ref_ptr<const RefMatrix> _initialViewMatrix;
ref_ptr<const RefMatrix> _projection; ref_ptr<const RefMatrix> _projection;
ref_ptr<const RefMatrix> _modelView; ref_ptr<const RefMatrix> _modelView;
Matrix _initialInverseViewMatrix; Matrix _initialInverseViewMatrix;
ref_ptr<DisplaySettings> _displaySettings; ref_ptr<DisplaySettings> _displaySettings;
bool* _abortRenderingPtr; bool* _abortRenderingPtr;
bool _reportGLErrors; bool _reportGLErrors;
@ -708,7 +731,7 @@ class SG_EXPORT State : public Referenced
last_applied_value = false; last_applied_value = false;
global_default_value = false; global_default_value = false;
} }
bool changed; bool changed;
bool last_applied_value; bool last_applied_value;
bool global_default_value; bool global_default_value;
@ -732,9 +755,17 @@ class SG_EXPORT State : public Referenced
ref_ptr<const StateAttribute> global_default_attribute; ref_ptr<const StateAttribute> global_default_attribute;
AttributeVec attributeVec; AttributeVec attributeVec;
}; };
/** 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) inline bool applyMode(StateAttribute::GLMode mode,bool enabled,ModeStack& ms)
{ {
if (ms.last_applied_value != enabled) if (ms.last_applied_value != enabled)
@ -762,9 +793,9 @@ class SG_EXPORT State : public Referenced
as.last_applied_attribute = attribute; as.last_applied_attribute = attribute;
attribute->apply(*this); attribute->apply(*this);
if (_reportGLErrors) checkGLErrors(attribute); if (_reportGLErrors) checkGLErrors(attribute);
return true; return true;
} }
else else
@ -786,7 +817,7 @@ class SG_EXPORT State : public Referenced
else else
return false; return false;
} }
typedef std::map<StateAttribute::GLMode,ModeStack> ModeMap; typedef std::map<StateAttribute::GLMode,ModeStack> ModeMap;
typedef std::vector<ModeMap> TextureModeMapList; typedef std::vector<ModeMap> TextureModeMapList;
@ -802,21 +833,21 @@ class SG_EXPORT State : public Referenced
TextureModeMapList _textureModeMapList; TextureModeMapList _textureModeMapList;
TextureAttributeMapList _textureAttributeMapList; TextureAttributeMapList _textureAttributeMapList;
StateSetStack _drawStateStack; StateSetStack _drawStateStack;
struct EnabledArrayPair struct EnabledArrayPair
{ {
EnabledArrayPair():_dirty(true),_enabled(false),_normalized(0),_pointer(0) {} EnabledArrayPair():_dirty(true),_enabled(false),_normalized(0),_pointer(0) {}
EnabledArrayPair(const EnabledArrayPair& eap):_dirty(eap._dirty), _enabled(eap._enabled),_normalized(eap._normalized),_pointer(eap._pointer) {} EnabledArrayPair(const EnabledArrayPair& eap):_dirty(eap._dirty), _enabled(eap._enabled),_normalized(eap._normalized),_pointer(eap._pointer) {}
EnabledArrayPair& operator = (const EnabledArrayPair& eap) { _dirty=eap._dirty; _enabled=eap._enabled; _normalized=eap._normalized;_pointer=eap._pointer; return *this; } EnabledArrayPair& operator = (const EnabledArrayPair& eap) { _dirty=eap._dirty; _enabled=eap._enabled; _normalized=eap._normalized;_pointer=eap._pointer; return *this; }
bool _dirty; bool _dirty;
bool _enabled; bool _enabled;
GLboolean _normalized; GLboolean _normalized;
const GLvoid* _pointer; const GLvoid* _pointer;
}; };
typedef std::vector<EnabledArrayPair> EnabledTexCoordArrayList; typedef std::vector<EnabledArrayPair> EnabledTexCoordArrayList;
typedef std::vector<EnabledArrayPair> EnabledVertexAttribArrayList; typedef std::vector<EnabledArrayPair> EnabledVertexAttribArrayList;
@ -831,29 +862,29 @@ class SG_EXPORT State : public Referenced
unsigned int _currentActiveTextureUnit; unsigned int _currentActiveTextureUnit;
unsigned int _currentClientActiveTextureUnit; unsigned int _currentClientActiveTextureUnit;
inline ModeMap& getOrCreateTextureModeMap(unsigned int unit) inline ModeMap& getOrCreateTextureModeMap(unsigned int unit)
{ {
if (unit>=_textureModeMapList.size()) _textureModeMapList.resize(unit+1); if (unit>=_textureModeMapList.size()) _textureModeMapList.resize(unit+1);
return _textureModeMapList[unit]; return _textureModeMapList[unit];
} }
inline AttributeMap& getOrCreateTextureAttributeMap(unsigned int unit) inline AttributeMap& getOrCreateTextureAttributeMap(unsigned int unit)
{ {
if (unit>=_textureAttributeMapList.size()) _textureAttributeMapList.resize(unit+1); if (unit>=_textureAttributeMapList.size()) _textureAttributeMapList.resize(unit+1);
return _textureAttributeMapList[unit]; return _textureAttributeMapList[unit];
} }
inline void pushModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void pushModeList(ModeMap& modeMap,const StateSet::ModeList& modeList);
inline void pushAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); inline void pushAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList);
inline void popModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void popModeList(ModeMap& modeMap,const StateSet::ModeList& modeList);
inline void popAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); inline void popAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList);
inline void applyModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void applyModeList(ModeMap& modeMap,const StateSet::ModeList& modeList);
inline void applyAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); inline void applyAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList);
inline void applyModeMap(ModeMap& modeMap); inline void applyModeMap(ModeMap& modeMap);
inline void applyAttributeMap(AttributeMap& attributeMap); inline void applyAttributeMap(AttributeMap& attributeMap);
@ -892,12 +923,12 @@ inline void State::pushModeList(ModeMap& modeMap,const StateSet::ModeList& modeL
// first pair so simply push incoming pair to back. // first pair so simply push incoming pair to back.
ms.valueVec.push_back(mitr->second); ms.valueVec.push_back(mitr->second);
} }
else if ((ms.valueVec.back() & StateAttribute::OVERRIDE) && !(mitr->second & StateAttribute::PROTECTED)) // check the existing override flag else if ((ms.valueVec.back() & StateAttribute::OVERRIDE) && !(mitr->second & StateAttribute::PROTECTED)) // check the existing override flag
{ {
// push existing back since override keeps the previous value. // push existing back since override keeps the previous value.
ms.valueVec.push_back(ms.valueVec.back()); ms.valueVec.push_back(ms.valueVec.back());
} }
else else
{ {
// no override on so simply push incoming pair to back. // no override on so simply push incoming pair to back.
ms.valueVec.push_back(mitr->second); ms.valueVec.push_back(mitr->second);
@ -920,12 +951,12 @@ inline void State::pushAttributeList(AttributeMap& attributeMap,const StateSet::
as.attributeVec.push_back( as.attributeVec.push_back(
AttributePair(aitr->second.first.get(),aitr->second.second)); AttributePair(aitr->second.first.get(),aitr->second.second));
} }
else if ((as.attributeVec.back().second & StateAttribute::OVERRIDE) && !(aitr->second.second & StateAttribute::PROTECTED)) // check the existing override flag else if ((as.attributeVec.back().second & StateAttribute::OVERRIDE) && !(aitr->second.second & StateAttribute::PROTECTED)) // check the existing override flag
{ {
// push existing back since override keeps the previous value. // push existing back since override keeps the previous value.
as.attributeVec.push_back(as.attributeVec.back()); as.attributeVec.push_back(as.attributeVec.back());
} }
else else
{ {
// no override on so simply push incoming pair to back. // no override on so simply push incoming pair to back.
as.attributeVec.push_back( as.attributeVec.push_back(
@ -1002,7 +1033,7 @@ inline void State::applyModeList(ModeMap& modeMap,const StateSet::ModeList& mode
else if (ds_mitr->first<this_mitr->first) else if (ds_mitr->first<this_mitr->first)
{ {
// ds_mitr->first is a new mode, therefore // ds_mitr->first is a new mode, therefore
// need to insert a new mode entry for ds_mistr->first. // need to insert a new mode entry for ds_mistr->first.
ModeStack& ms = modeMap[ds_mitr->first]; ModeStack& ms = modeMap[ds_mitr->first];
@ -1072,7 +1103,7 @@ inline void State::applyModeList(ModeMap& modeMap,const StateSet::ModeList& mode
} }
} }
} }
// iterator over the remaining incoming modes to apply any new mode. // iterator over the remaining incoming modes to apply any new mode.
for(; for(;
@ -1122,7 +1153,7 @@ inline void State::applyAttributeList(AttributeMap& attributeMap,const StateSet:
else if (ds_aitr->first<this_aitr->first) else if (ds_aitr->first<this_aitr->first)
{ {
// ds_aitr->first is a new attribute, therefore // ds_aitr->first is a new attribute, therefore
// need to insert a new attribute entry for ds_aitr->first. // need to insert a new attribute entry for ds_aitr->first.
AttributeStack& as = attributeMap[ds_aitr->first]; AttributeStack& as = attributeMap[ds_aitr->first];
@ -1188,14 +1219,14 @@ inline void State::applyAttributeList(AttributeMap& attributeMap,const StateSet:
applyGlobalDefaultAttribute(as); applyGlobalDefaultAttribute(as);
} }
} }
} }
// iterator over the remaining incoming modes to apply any new mode. // iterator over the remaining incoming modes to apply any new mode.
for(; for(;
ds_aitr!=attributeList.end(); ds_aitr!=attributeList.end();
++ds_aitr) ++ds_aitr)
{ {
// ds_aitr->first is a new attribute, therefore // ds_aitr->first is a new attribute, therefore
// need to insert a new attribute entry for ds_aitr->first. // need to insert a new attribute entry for ds_aitr->first.
AttributeStack& as = attributeMap[ds_aitr->first]; AttributeStack& as = attributeMap[ds_aitr->first];
@ -1229,9 +1260,9 @@ inline void State::applyModeMap(ModeMap& modeMap)
// assume default of disabled. // assume default of disabled.
applyMode(mitr->first,ms.global_default_value,ms); applyMode(mitr->first,ms.global_default_value,ms);
} }
} }
} }
} }
inline void State::applyAttributeMap(AttributeMap& attributeMap) inline void State::applyAttributeMap(AttributeMap& attributeMap)
@ -1253,9 +1284,9 @@ inline void State::applyAttributeMap(AttributeMap& attributeMap)
{ {
applyGlobalDefaultAttribute(as); applyGlobalDefaultAttribute(as);
} }
} }
} }
} }
} }

125
include/osg/StateSet
View File

@ -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 * 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 * 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 * (at your option) any later version. The full license is in LICENSE file
* included with this distribution, and on the openscenegraph.org website. * included with this distribution, and on the openscenegraph.org website.
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * 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. * OpenSceneGraph Public License for more details.
*/ */
@ -29,18 +29,20 @@
namespace osg { namespace osg {
/** /** Stores a set of modes and attributes which respresent a set of OpenGL state.
Encapsulates OpenGL state modes and attributes. * Notice that a \c StateSet contains just a subset of the whole OpenGL state.
Used to specific textures etc of osg::Drawable's which hold references * <p>In OSG, each \c Drawable and each \c Node has a reference to a
to a single osg::StateSet. StateSet can be shared between Drawable's * \c StateSet. These <tt>StateSet</tt>s can be shared between
and is recommend if possible as it minimizes expensive state changes * different <tt>Drawable</tt>s and <tt>Node</tt>s (that is, several
in the graphics pipeline. * <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 class SG_EXPORT StateSet : public Object
{ {
public : public :
StateSet(); StateSet();
StateSet(const StateSet&,const CopyOp& copyop=CopyOp::SHALLOW_COPY); StateSet(const StateSet&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
@ -52,12 +54,12 @@ class SG_EXPORT StateSet : public Object
/** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/ /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/
int compare(const StateSet& rhs,bool compareAttributeContents=false) const; int compare(const StateSet& rhs,bool compareAttributeContents=false) const;
bool operator < (const StateSet& rhs) const { return compare(rhs)<0; } bool operator < (const StateSet& rhs) const { return compare(rhs)<0; }
bool operator == (const StateSet& rhs) const { return compare(rhs)==0; } bool operator == (const StateSet& rhs) const { return compare(rhs)==0; }
bool operator != (const StateSet& rhs) const { return compare(rhs)!=0; } bool operator != (const StateSet& rhs) const { return compare(rhs)!=0; }
/** Set all the modes to on or off so that it defines a /** Set all the modes to on or off so that it defines a
complete state, typically used for a default global state.*/ complete state, typically used for a default global state.*/
void setGlobalDefaults(); void setGlobalDefaults();
@ -70,42 +72,65 @@ class SG_EXPORT StateSet : public Object
/** Clear the StateSet of all modes and attributes.*/ /** Clear the StateSet of all modes and attributes.*/
void clear(); void clear();
/** merge this stateset with stateset rhs, this overrides /** Merge this \c StateSet with the \c StateSet passed as parameter.
* the rhs if OVERRIDE is specified, otherwise rhs takes precedence.*/ * 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); void merge(const StateSet& rhs);
/** a container to map GLModes to their respective GLModeValues.*/ /** a container to map GLModes to their respective GLModeValues.*/
typedef std::map<StateAttribute::GLMode,StateAttribute::GLModeValue> ModeList; 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); void setMode(StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
#ifdef USE_DEPRECATED_API #ifdef USE_DEPRECATED_API
/** Set this StateSet to inherit specified GLMode type from parents. /** Set this StateSet to inherit specified GLMode type from parents.
* Has the effect of deleting any GLMode of specified type from StateSet.*/ * Has the effect of deleting any GLMode of specified type from StateSet.*/
void setModeToInherit(StateAttribute::GLMode mode) { removeMode(mode); } void setModeToInherit(StateAttribute::GLMode mode) { removeMode(mode); }
#endif #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); void removeMode(StateAttribute::GLMode mode);
/** Get specified GLModeValue for specified GLMode. /** Get the value for a given \c GLMode.
* returns INHERIT if no GLModeValue is contained within StateSet.*/ * @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; 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; } 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; } 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; } inline const ModeList& getModeList() const { return _modeList; }
/** Simple pairing between an attribute and its override flag.*/ /** Simple pairing between an attribute and its override flag.*/
typedef std::pair<ref_ptr<StateAttribute>,StateAttribute::OverrideValue> RefAttributePair; typedef std::pair<ref_ptr<StateAttribute>,StateAttribute::OverrideValue> RefAttributePair;
/** a container to map <StateAttribyte::Types,Member> to their respective RefAttributePair.*/ /** a container to map <StateAttribyte::Types,Member> to their respective RefAttributePair.*/
typedef std::map<StateAttribute::TypeMemberPair,RefAttributePair> AttributeList; typedef std::map<StateAttribute::TypeMemberPair,RefAttributePair> AttributeList;
@ -137,7 +162,7 @@ class SG_EXPORT StateSet : public Object
/** Get specified RefAttributePair for specified type. /** Get specified RefAttributePair for specified type.
* Returns NULL if no type is contained within StateSet.*/ * Returns NULL if no type is contained within StateSet.*/
const RefAttributePair* getAttributePair(StateAttribute::Type type, unsigned int member = 0) const; const RefAttributePair* getAttributePair(StateAttribute::Type type, unsigned int member = 0) const;
/** set the list of all StateAttributes contained in this StateSet.*/ /** set the list of all StateAttributes contained in this StateSet.*/
inline void setAttributeList(AttributeList& al) { _attributeList=al; } inline void setAttributeList(AttributeList& al) { _attributeList=al; }
@ -151,7 +176,13 @@ class SG_EXPORT StateSet : public Object
typedef std::vector<ModeList> TextureModeList; 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); void setTextureMode(unsigned int unit,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
#ifdef USE_DEPRECATED_API #ifdef USE_DEPRECATED_API
@ -206,7 +237,7 @@ class SG_EXPORT StateSet : public Object
/** Get specified Texture related RefAttributePair for specified type. /** Get specified Texture related RefAttributePair for specified type.
* Returns NULL if no type is contained within StateSet.*/ * Returns NULL if no type is contained within StateSet.*/
const RefAttributePair* getTextureAttributePair(unsigned int unit,StateAttribute::Type type) const; const RefAttributePair* getTextureAttributePair(unsigned int unit,StateAttribute::Type type) const;
/** Set the list of all Texture related StateAttributes contained in this StateSet.*/ /** Set the list of all Texture related StateAttributes contained in this StateSet.*/
inline void setTextureAttributeList(TextureAttributeList& tal) { _textureAttributeList=tal; } inline void setTextureAttributeList(TextureAttributeList& tal) { _textureAttributeList=tal; }
@ -218,7 +249,7 @@ class SG_EXPORT StateSet : public Object
void setAssociatedModes(const StateAttribute* attribute, StateAttribute::GLModeValue value); void setAssociatedModes(const StateAttribute* attribute, StateAttribute::GLModeValue value);
void setAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute, StateAttribute::GLModeValue value); void setAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute, StateAttribute::GLModeValue value);
enum RenderingHint enum RenderingHint
@ -227,15 +258,21 @@ class SG_EXPORT StateSet : public Object
OPAQUE_BIN = 1, OPAQUE_BIN = 1,
TRANSPARENT_BIN = 2 TRANSPARENT_BIN = 2
}; };
/** Set the RenderingHint of the StateSet. /** Set the \c RenderingHint of this \c StateSet. \c RenderingHint is
* RenderingHint is used by osgUtil::Renderer to determine which * used by the renderer to determine which draw bin to drop associated
* draw bin to drop associated osg::Drawables in. For opaque * <tt>osg::Drawable</tt>s in. Typically, users will set this to either
* objects OPAQUE_BIN would typical used, which TRANSPARENT_BIN * \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN.
* should be used for objects which need to be depth sorted.*/ * <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); void setRenderingHint(int hint);
/** Get the RenderingHint of the StateSet.*/ /** Get the \c RenderingHint of this \c StateSet.*/
inline int getRenderingHint() const { return _renderingHint; } inline int getRenderingHint() const { return _renderingHint; }
enum RenderBinMode enum RenderBinMode
@ -248,10 +285,10 @@ class SG_EXPORT StateSet : public Object
/** Set the render bin details.*/ /** Set the render bin details.*/
void setRenderBinDetails(int binNum,const std::string& binName,RenderBinMode mode=USE_RENDERBIN_DETAILS); void setRenderBinDetails(int binNum,const std::string& binName,RenderBinMode mode=USE_RENDERBIN_DETAILS);
/** Set the render bin details to inherit.*/ /** Set the render bin details to inherit.*/
void setRenderBinToInherit(); void setRenderBinToInherit();
/** Get whether the render bin details are set and should be used.*/ /** Get whether the render bin details are set and should be used.*/
inline bool useRenderBinDetails() const { return _binMode!=INHERIT_RENDERBIN_DETAILS; } inline bool useRenderBinDetails() const { return _binMode!=INHERIT_RENDERBIN_DETAILS; }
@ -273,7 +310,7 @@ class SG_EXPORT StateSet : public Object
/** Get the render bin name.*/ /** Get the render bin name.*/
inline const std::string& getBinName() const { return _binName; } inline const std::string& getBinName() const { return _binName; }
/** call compile on all StateAttributes contained within this StateSet.*/ /** call compile on all StateAttributes contained within this StateSet.*/
void compileGLObjects(State& state) const; void compileGLObjects(State& state) const;
@ -286,25 +323,25 @@ class SG_EXPORT StateSet : public Object
virtual ~StateSet(); virtual ~StateSet();
StateSet& operator = (const StateSet&) { return *this; } StateSet& operator = (const StateSet&) { return *this; }
ModeList _modeList; ModeList _modeList;
AttributeList _attributeList; AttributeList _attributeList;
TextureModeList _textureModeList; TextureModeList _textureModeList;
TextureAttributeList _textureAttributeList; TextureAttributeList _textureAttributeList;
inline ModeList& getOrCreateTextureModeList(unsigned int unit) inline ModeList& getOrCreateTextureModeList(unsigned int unit)
{ {
if (unit>=_textureModeList.size()) _textureModeList.resize(unit+1); if (unit>=_textureModeList.size()) _textureModeList.resize(unit+1);
return _textureModeList[unit]; return _textureModeList[unit];
} }
inline AttributeList& getOrCreateTextureAttributeList(unsigned int unit) inline AttributeList& getOrCreateTextureAttributeList(unsigned int unit)
{ {
if (unit>=_textureAttributeList.size()) _textureAttributeList.resize(unit+1); if (unit>=_textureAttributeList.size()) _textureAttributeList.resize(unit+1);
return _textureAttributeList[unit]; return _textureAttributeList[unit];
} }
int compareModes(const ModeList& lhs,const ModeList& rhs); int compareModes(const ModeList& lhs,const ModeList& rhs);
int compareAttributePtrs(const AttributeList& lhs,const AttributeList& rhs); int compareAttributePtrs(const AttributeList& lhs,const AttributeList& rhs);
int compareAttributeContents(const AttributeList& lhs,const AttributeList& rhs); int compareAttributeContents(const AttributeList& lhs,const AttributeList& rhs);