diff --git a/include/osg/Drawable b/include/osg/Drawable index 1050a4e4b..2457edfe8 100644 --- a/include/osg/Drawable +++ b/include/osg/Drawable @@ -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. - *

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; diff --git a/include/osg/State b/include/osg/State index 31221882b..10defa9cf 100644 --- a/include/osg/State +++ b/include/osg/State @@ -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. */ @@ -48,7 +48,7 @@ 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.*/ #define OSG_GL_DEBUG(message) \ if (state.getFineGrainedErrorDetection()) \ @@ -60,13 +60,25 @@ 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 { public : - + State(); /** Push stateset onto state stack.*/ @@ -74,7 +86,7 @@ class SG_EXPORT State : public Referenced /** Pop stateset off state stack.*/ void popStateSet(); - + /** 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().*/ void popAllStateSets(); @@ -84,12 +96,12 @@ class SG_EXPORT State : public Referenced /** reset the state object to an empty stack.*/ void reset(); - + inline const Viewport* getCurrentViewport() const { return static_cast(getLastAppliedAttribute(osg::StateAttribute::VIEWPORT)); } - + void setInitialViewMatrix(const osg::RefMatrix* matrix); @@ -101,7 +113,7 @@ class SG_EXPORT State : public Referenced if (_projection!=matrix) { glMatrixMode( GL_PROJECTION ); - if (matrix) + if (matrix) { _projection=matrix; glLoadMatrix(matrix->ptr()); @@ -114,7 +126,7 @@ class SG_EXPORT State : public Referenced glMatrixMode( GL_MODELVIEW ); } } - + inline const osg::Matrix& getProjectionMatrix() const { return *_projection; @@ -129,7 +141,7 @@ class SG_EXPORT State : public Referenced _modelView=matrix; glLoadMatrix(matrix->ptr()); } - else + else { _modelView=_identity; glLoadIdentity(); @@ -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 StateSets maintained internally by a + * \c State. + */ 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) { ModeStack& ms = _modeMap[mode]; - ms.changed = true; + ms.changed = true; return applyMode(mode,enabled,ms); } @@ -247,10 +270,10 @@ class SG_EXPORT State : public Referenced else return false; } - + /** Mode has been set externally, update state to reflect this setting.*/ void haveAppliedMode(StateAttribute::GLMode mode,StateAttribute::GLModeValue value); - + /** Mode has been set externally, therefore dirty the associated mode in osg::State * so it is applied on next call to osg::State::apply(..)*/ 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).*/ bool getLastAppliedMode(StateAttribute::GLMode mode) const; - + /** 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; - + /** texture Mode has been set externally, update state to reflect this setting.*/ 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 * so it is applied on next call to osg::State::apply(..)*/ 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.*/ void haveAppliedTextureAttribute(unsigned int unit, const StateAttribute* attribute); - /** texture Attribute has been applied externally, - * and therefore this attribute type has been dirtied + /** texture Attribute has been applied externally, + * and therefore this attribute type has been dirtied * and will need to be re-appplied on next osg::State.apply(..). * 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 @@ -292,10 +315,10 @@ class SG_EXPORT State : public Referenced * that only changed state will be applied.*/ 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; - - /** 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; @@ -335,7 +358,7 @@ class SG_EXPORT State : public Referenced } _vertexArray._dirty = false; } - + /** wrapper around glDisableClientState(GL_VERTEX_ARRAY). * note, only updates values that change.*/ inline void disableVertexPointer() @@ -350,8 +373,8 @@ class SG_EXPORT State : public Referenced inline void dirtyVertexPointer() { - _vertexArray._pointer = 0; - _vertexArray._dirty = true; + _vertexArray._pointer = 0; + _vertexArray._dirty = true; } /** wrapper around glEnableClientState(GL_NORMAL_ARRAY);glNormalPointer(..); @@ -421,7 +444,7 @@ class SG_EXPORT State : public Referenced } inline void dirtyColorPointer() - { + { _colorArray._pointer = 0; _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. * note, only updates values that change.*/ 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. * note, only updates values that change.*/ bool setActiveTextureUnit( unsigned int unit ); - + /** wrapper around glEnableVertexAttribArrayARB(index);glVertexAttribPointerARB(..); * note, only updates values that change.*/ void setVertexAttribPointer( unsigned int index, - GLint size, GLenum type, GLboolean normalized, + GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid *ptr ); - + /** wrapper around DisableVertexAttribArrayARB(index); * note, only updates values that change.*/ void disableVertexAttribPointer( unsigned int index ); - + void disableVertexAttribPointersAboveAndIncluding( unsigned int index ); - + inline void dirtyVertexAttribPointersAboveAndIncluding( unsigned int index ) { while (index<_vertexAttribArrayList.size()) @@ -640,37 +663,37 @@ class SG_EXPORT State : public Referenced arrays that they maintain for the purpose. Typical settings for contextID are 0,1,2,3... up to the maximum 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; } - /** Get the current OpenGL context unique ID.*/ + /** Get the current OpenGL context unique ID.*/ inline unsigned int getContextID() const { return _contextID; } - - + + /** Set the frame stamp for the current frame.*/ inline void setFrameStamp(FrameStamp* fs) { _frameStamp = fs; } /** Get the frame stamp for the current frame.*/ inline const FrameStamp* getFrameStamp() const { return _frameStamp.get(); } - - + + /** 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 * during rendering. */ inline void setDisplaySettings(DisplaySettings* vs) { _displaySettings = vs; } - + /** Get the DisplaySettings */ inline const DisplaySettings* getDisplaySettings() const { return _displaySettings.get(); } typedef std::pair AttributePair; typedef std::vector AttributeVec; typedef std::vector ValueVec; - - + + /** Set flag for early termination of the draw traversal.*/ 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.*/ bool getAbortRendering() const { return _abortRenderingPtr!=0?(*_abortRenderingPtr):false; } @@ -687,16 +710,16 @@ class SG_EXPORT State : public Referenced unsigned int _contextID; ref_ptr _frameStamp; - + ref_ptr _identity; ref_ptr _initialViewMatrix; ref_ptr _projection; ref_ptr _modelView; - + Matrix _initialInverseViewMatrix; ref_ptr _displaySettings; - + bool* _abortRenderingPtr; bool _reportGLErrors; @@ -708,7 +731,7 @@ class SG_EXPORT State : public Referenced last_applied_value = false; global_default_value = false; } - + bool changed; bool last_applied_value; bool global_default_value; @@ -732,9 +755,17 @@ class SG_EXPORT State : public Referenced ref_ptr global_default_attribute; 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) { if (ms.last_applied_value != enabled) @@ -762,9 +793,9 @@ class SG_EXPORT State : public Referenced as.last_applied_attribute = attribute; attribute->apply(*this); - + if (_reportGLErrors) checkGLErrors(attribute); - + return true; } else @@ -786,7 +817,7 @@ class SG_EXPORT State : public Referenced else return false; } - + typedef std::map ModeMap; typedef std::vector TextureModeMapList; @@ -802,21 +833,21 @@ class SG_EXPORT State : public Referenced TextureModeMapList _textureModeMapList; TextureAttributeMapList _textureAttributeMapList; - + StateSetStack _drawStateStack; - + struct EnabledArrayPair { 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& operator = (const EnabledArrayPair& eap) { _dirty=eap._dirty; _enabled=eap._enabled; _normalized=eap._normalized;_pointer=eap._pointer; return *this; } - + bool _dirty; bool _enabled; GLboolean _normalized; const GLvoid* _pointer; }; - + typedef std::vector EnabledTexCoordArrayList; typedef std::vector EnabledVertexAttribArrayList; @@ -831,29 +862,29 @@ class SG_EXPORT State : public Referenced unsigned int _currentActiveTextureUnit; unsigned int _currentClientActiveTextureUnit; - + inline ModeMap& getOrCreateTextureModeMap(unsigned int unit) - { + { if (unit>=_textureModeMapList.size()) _textureModeMapList.resize(unit+1); return _textureModeMapList[unit]; } inline AttributeMap& getOrCreateTextureAttributeMap(unsigned int unit) - { + { if (unit>=_textureAttributeMapList.size()) _textureAttributeMapList.resize(unit+1); return _textureAttributeMapList[unit]; } - + inline void pushModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void pushAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); - + inline void popModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void popAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); inline void applyModeList(ModeMap& modeMap,const StateSet::ModeList& modeList); inline void applyAttributeList(AttributeMap& attributeMap,const StateSet::AttributeList& attributeList); - + inline void applyModeMap(ModeMap& modeMap); 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. 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. ms.valueVec.push_back(ms.valueVec.back()); } - else + else { // no override on so simply push incoming pair to back. ms.valueVec.push_back(mitr->second); @@ -920,12 +951,12 @@ inline void State::pushAttributeList(AttributeMap& attributeMap,const StateSet:: as.attributeVec.push_back( 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. as.attributeVec.push_back(as.attributeVec.back()); } - else + else { // no override on so simply push incoming pair to back. as.attributeVec.push_back( @@ -1002,7 +1033,7 @@ inline void State::applyModeList(ModeMap& modeMap,const StateSet::ModeList& mode else if (ds_mitr->firstfirst) { - // 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. 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. for(; @@ -1122,7 +1153,7 @@ inline void State::applyAttributeList(AttributeMap& attributeMap,const StateSet: else if (ds_aitr->firstfirst) { - // 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. AttributeStack& as = attributeMap[ds_aitr->first]; @@ -1188,14 +1219,14 @@ inline void State::applyAttributeList(AttributeMap& attributeMap,const StateSet: applyGlobalDefaultAttribute(as); } } - } + } // iterator over the remaining incoming modes to apply any new mode. for(; ds_aitr!=attributeList.end(); ++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. AttributeStack& as = attributeMap[ds_aitr->first]; @@ -1229,9 +1260,9 @@ inline void State::applyModeMap(ModeMap& modeMap) // assume default of disabled. applyMode(mitr->first,ms.global_default_value,ms); } - + } - } + } } inline void State::applyAttributeMap(AttributeMap& attributeMap) @@ -1253,9 +1284,9 @@ inline void State::applyAttributeMap(AttributeMap& attributeMap) { applyGlobalDefaultAttribute(as); } - + } - } + } } } diff --git a/include/osg/StateSet b/include/osg/StateSet index 34aaba9d0..bfc5f31ae 100644 --- a/include/osg/StateSet +++ b/include/osg/StateSet @@ -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. */ @@ -29,18 +29,20 @@ 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. + *

In OSG, each \c Drawable and each \c Node has a reference to a + * \c StateSet. These StateSets can be shared between + * different Drawables and Nodes (that is, several + * Drawables and Nodes 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 { public : - - + + StateSet(); 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.*/ 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; } - /** 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.*/ void setGlobalDefaults(); @@ -70,42 +72,65 @@ 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 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 /** Set this StateSet to inherit specified GLMode type from parents. * 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 GLModes 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 GLModes 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 GLModes contained in this + * const StateSet. + */ inline const ModeList& getModeList() const { return _modeList; } /** Simple pairing between an attribute and its override flag.*/ typedef std::pair,StateAttribute::OverrideValue> RefAttributePair; - + /** a container to map to their respective RefAttributePair.*/ typedef std::map AttributeList; @@ -137,7 +162,7 @@ class SG_EXPORT StateSet : public Object /** Get specified RefAttributePair for specified type. * Returns NULL if no type is contained within StateSet.*/ const RefAttributePair* getAttributePair(StateAttribute::Type type, unsigned int member = 0) const; - + /** set the list of all StateAttributes contained in this StateSet.*/ inline void setAttributeList(AttributeList& al) { _attributeList=al; } @@ -151,7 +176,13 @@ class SG_EXPORT StateSet : public Object typedef std::vector 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 @@ -206,7 +237,7 @@ class SG_EXPORT StateSet : public Object /** Get specified Texture related RefAttributePair for specified type. * Returns NULL if no type is contained within StateSet.*/ const RefAttributePair* getTextureAttributePair(unsigned int unit,StateAttribute::Type type) const; - + /** Set the list of all Texture related StateAttributes contained in this StateSet.*/ 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 setAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute, StateAttribute::GLModeValue value); enum RenderingHint @@ -227,15 +258,21 @@ class SG_EXPORT StateSet : public Object OPAQUE_BIN = 1, 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 + * osg::Drawables in. Typically, users will set this to either + * \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN. + * Drawables in the opaque bin are sorted by their + * \c StateSet, so that the number of expensive changes in the OpenGL + * state is minimized. Drawables 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 @@ -248,10 +285,10 @@ class SG_EXPORT StateSet : public Object /** Set the render bin details.*/ void setRenderBinDetails(int binNum,const std::string& binName,RenderBinMode mode=USE_RENDERBIN_DETAILS); - + /** Set the render bin details to inherit.*/ void setRenderBinToInherit(); - + /** Get whether the render bin details are set and should be used.*/ inline bool useRenderBinDetails() const { return _binMode!=INHERIT_RENDERBIN_DETAILS; } @@ -273,7 +310,7 @@ class SG_EXPORT StateSet : public Object /** Get the render bin name.*/ inline const std::string& getBinName() const { return _binName; } - + /** call compile on all StateAttributes contained within this StateSet.*/ void compileGLObjects(State& state) const; @@ -286,25 +323,25 @@ class SG_EXPORT StateSet : public Object virtual ~StateSet(); StateSet& operator = (const StateSet&) { return *this; } - + ModeList _modeList; AttributeList _attributeList; TextureModeList _textureModeList; TextureAttributeList _textureAttributeList; - + inline ModeList& getOrCreateTextureModeList(unsigned int unit) { if (unit>=_textureModeList.size()) _textureModeList.resize(unit+1); return _textureModeList[unit]; } - + inline AttributeList& getOrCreateTextureAttributeList(unsigned int unit) { if (unit>=_textureAttributeList.size()) _textureAttributeList.resize(unit+1); return _textureAttributeList[unit]; } - + int compareModes(const ModeList& lhs,const ModeList& rhs); int compareAttributePtrs(const AttributeList& lhs,const AttributeList& rhs); int compareAttributeContents(const AttributeList& lhs,const AttributeList& rhs);